Conversational Actions will be deprecated on June 13, 2023. For more information, see Conversational Actions sunset.

Link Asisten

Anda dapat membuat URL yang tertaut langsung ke intent tertentu dari Action Anda. Pengguna yang mengklik link Asisten (sebelumnya disebut link Tindakan) di browser web atau seluler akan diarahkan ke Asisten di perangkat mereka, tempat mereka berinteraksi langsung dengan Action Anda.

Link Asisten berbeda dengan link web direktori, yang mengarahkan pengguna ke halaman Action Anda di direktori Asisten.

Berikut adalah beberapa situasi di mana link Asisten dapat berguna:

  • Menautkan pengguna ke petunjuk panduan suara dari situs petunjuk.
  • Menautkan pengguna ke pengalaman dukungan pelanggan dari halaman bantuan.
  • Menautkan pengguna ke intent update agar mereka dapat ikut serta dalam update mendatang.

Anda dapat membuat link Asisten dari dalam project di Konsol Actions. Link Asisten tersedia melalui semua saluran deployment (alfa, beta, dan produksi). Misalnya, jika link Asisten Anda diaktifkan di rilis alfa Action, link tersebut akan tersedia untuk penguji alfa.

Untuk membuat URL bagi Action, ikuti langkah-langkah berikut:

  1. Di konsol Actions, buka Deploy > Link Asisten.
  2. Untuk Intent, pilih intent yang ingin Anda buatkan linknya.
  3. Aktifkan opsi Apakah Anda ingin mengaktifkan penautan untuk intent_name?.
  4. (opsional) Di bagian Parameter kampanye, masukkan informasi apa pun yang ingin Anda ambil juga di link sebagai parameter URL.
  5. (opsional) Masukkan Judul link. Gunakan judul ini untuk menjelaskan fungsi Action. Misalnya, jika Action Anda mengarahkan pengguna ke alur transaksi untuk membeli tiket ke konser, judul link Anda bisa menjadi "membeli tiket konser".

Setelah memasukkan informasi, Anda dapat melihat dan menyalin URL yang dihasilkan atau cuplikan kode yang dibuat untuk link Asisten. Gunakan link Asisten di mana pun Anda ingin mengarahkan pengguna ke Action tertentu ini.

Anda dapat menguji link Asisten untuk intent apa pun (utama atau kustom, dengan atau tanpa parameter) melalui simulator atau di perangkat.

Untuk menguji link Asisten di perangkat, ikuti langkah-langkah berikut:

  1. Buat link Asisten di konsol Actions.
  2. Kirim link Asisten sebagai URL ke diri sendiri di email, pesan chat, atau format lainnya.
  3. Di perangkat yang dilengkapi dengan Asisten, login ke Asisten dengan akun yang sama seperti yang Anda gunakan untuk membuat project Actions.
  4. Di perangkat yang sama, klik link Asisten yang Anda kirim ke diri sendiri.

Setelah mengonfirmasi fungsi link Asisten seperti yang diharapkan, Anda harus men-deploy ulang Action Anda untuk membuat link tersedia bagi pengguna.

Link Asisten dapat berisi intent dan parameter di URL secara opsional. Gunakan bagian Parameter kampanye untuk menambahkan parameter kampanye.

Jika link Asisten tidak berisi parameter tambahan, Asisten Google akan menautkan ke intent MAIN (actions.intent.MAIN) Action Anda dengan perilaku berikut:

  • Jika Anda tidak secara eksplisit mengaktifkan intent MAIN di link Asisten, Asisten akan mencocokkan intent utama tanpa parameter apa pun, mirip dengan perilaku untuk "Talk to app_name".
  • Jika Anda secara eksplisit mengaktifkan intent MAIN, Asisten akan meneruskan parameter ke Action Anda.

Berikut adalah contoh URL link Asisten yang menggunakan intent MAIN tanpa parameter tambahan:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4

Sintaksis umum untuk URL link Asisten adalah sebagai berikut:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

Parameter URL yang dapat Anda tetapkan dijelaskan dalam tabel berikut:

Parameter URL Deskripsi
$action_id ID numerik tindakan.
$intent Nama lengkap intent pengguna atau bawaan.
$param Nama lengkap parameter intent yang ditentukan dalam paket Action.
$value Nilai yang dienkode URL dari jenis yang dideklarasikan untuk $param dalam paket Tindakan.
$utm_param Daftar satu atau beberapa jenis parameter UTM. Nilai yang valid meliputi: utm_source, utm_medium, utm_campaign, utm_term, dan utm_content.
$utm_value Nilai string parameter UTM.

Jika link Asisten berisi intent bawaan (intent dimulai dengan actions.intent.), Asisten Google akan mencoba mengekstrak parameter intent bawaan di URL dan meneruskannya ke Action Anda. Semua parameter yang tidak dipahami Asisten sebagai parameter intent bawaan akan dihapus.

Untuk Action Percakapan, Asisten mengirimkan parameter ini ke fulfillment Anda sebagai bagian dari pesan AppRequest.

Contoh berikut menunjukkan cara menentukan URL link Asisten yang menyertakan intent bawaan dengan parameter intent tunggal:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME&param.name=%22ExampleGame%22

Untuk intent pengguna, Asisten Google hanya mengekstrak parameter yang ditentukan oleh Action Anda sebagai bagian dari intent dan menghapus parameter lainnya.

Contoh berikut menunjukkan cara menetapkan URL link Asisten yang menyertakan intent pengguna:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

Untuk contoh URL di atas, di AppRequest, Asisten menambahkan objek JSON sebagai berikut:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

Parameter UTM adalah string yang dikirimkan Asisten Google ke Action Anda saat pengguna mengklik link Asisten. Anda dapat menggunakan informasi yang terdapat dalam string ini nanti untuk analisis.

Parameter UTM yang dikirim Asisten ke Action Anda mencakup hal berikut:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

Contoh berikut menunjukkan cara menentukan URL link Asisten yang menyertakan parameter UTM:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

Untuk contoh URL di atas, Asisten menambahkan argumen berikut dalam pesan AppRequest:

argument {
  name: 'utm_source',
  raw_text: 'Google',
  text_value: 'Google',
}
argument {
  name: 'utm_medium',
  raw_text: 'email',
  text_value: 'email',
}
argument {
  name: 'utm_campaign',
  raw_text: 'holiday sale',
  text_value: 'holiday sale',
}

Link Asisten yang kaya memberi Anda cara untuk meningkatkan penemuan Action melalui situs Anda, menggunakan help.js. Pengguna dapat mencoba Action Anda, serta menautkan Akun Google mereka ke layanan Anda menggunakan penautan akun.

Saat pengguna mengunjungi situs Anda, mereka melihat tombol "Coba dengan Asisten Google", yang memicu alur link Asisten yang kaya.

Mengaktifkan penautan akun untuk Action Anda memungkinkan pengguna mengakses Action di perangkat apa pun yang dilengkapi dengan Asisten. Selain itu, pengguna dapat menautkan akun mereka dengan layanan Anda ke Akun Google mereka, sehingga memberikan pengalaman yang lebih dipersonalisasi.

Saat digunakan dengan penautan akun, link Asisten Kaya menggunakan URL otorisasi Anda, yang ditetapkan di project Anda di konsol Actions. Untuk informasi selengkapnya, lihat dokumentasi penautan akun.

Prasyarat

Untuk menggunakan link Asisten yang kaya, Anda memerlukan hal berikut:

Pengembangan lokal

Untuk menyertakan link Asisten yang lengkap di situs Anda, selesaikan langkah-langkah berikut:

  1. Sertakan library JavaScript berikut di halaman Anda, yang menggantikan <PROJECT_ID> dengan project ID Actions Anda:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
    </script>
    
  2. Tambahkan tag HTML berikut di suatu tempat pada halaman Anda. Tindakan ini akan memuat tombol "Coba dengan Asisten Google" inline:

    <google-assistant-link-group>
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    

Pemicu proaktif

Jika Anda ingin alur link Asisten yang kaya dimulai secara otomatis saat pengguna mengunjungi halaman Anda untuk pertama kalinya, gunakan tag <google-assistant-proactive-link>. Jika Anda menerapkan tag ini, link akan diaktifkan tanpa pengguna pada kunjungan pertama, tanpa mereka memilih tombol inline.

  1. Tambahkan id ke tag grup link Asisten Anda:

    <google-assistant-link-group id="my-group">
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    
  2. Tempatkan tag <google-assistant-proactive-action-link> di halaman web Anda dan tetapkan atribut groupId-nya ke id:

    <google-assistant-link-group id="my-group">
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    
    <google-assistant-proactive-link
    groupId="my-group">
    </google-assistant-proactive-link>
    

Deployment

Link Asisten hanya berfungsi untuk domain yang Anda miliki dan telah diverifikasi dengan Google. Saat mengembangkan secara lokal, persyaratan ini diabaikan karena memiliki akses ke project Tindakan, login ke Akun Google Anda, dan menetapkan parameter kueri dev=true di tag skrip.

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

Untuk men-deploy Action dengan link Asisten yang lengkap:

  1. Daftarkan domain publik Anda di konsol Actions di bagian Deploy > Brand Verification > Connect Site.
  2. Hapus parameter kueri dev=true dari skrip:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}">
    </script>
    

Batasan dan praktik terbaik

Batasan dan praktik terbaik berikut berlaku sehingga URL link Asisten Anda dapat didistribusikan dan dirujuk di luar direktori atau layanan Google lainnya:

  • Terus dukung semua link Asisten Anda. Jika Anda mendistribusikan link Asisten yang nantinya rusak, project Action Anda dapat ditandai sebagai tidak responsif dan dihapus.
  • Memublikasikan link berarti Anda mendukung pemicu dari sumber yang tidak tepercaya. Untuk setiap Tindakan tertaut, Anda harus secara eksplisit mengonfirmasi dengan pengguna sebelum melakukan tindakan nyata. Misalnya, Action yang menonaktifkan perangkat smart home akan meminta pengguna untuk mengucapkan, "Yakin ingin menonaktifkan $applianceName?"

    Dalam konteks ini, tindakan nyata adalah tindakan apa pun yang memengaruhi layanan, data, perangkat, jaringan, komputer, atau API pengguna. Misalnya, mengirim email, melakukan transaksi, mengubah status perangkat smart home, membuat langganan, atau memperbarui konten.