Link Asisten

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

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

Berikut beberapa situasi ketika link Asisten dapat berguna:

  • Menghubungkan pengguna ke petunjuk dengan panduan suara dari situs petunjuk.
  • Menautkan pengguna ke pengalaman dukungan pelanggan dari halaman bantuan.
  • Menautkan pengguna ke intent update agar mereka dapat memilih untuk ikut serta pembaruan berikutnya.

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 dalam versi alfa rilis Action Anda, link ini tersedia untuk penguji alfa.

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

  1. Di Actions console, buka Deploy > Link Asisten.
  2. Untuk Intent, pilih intent yang ingin Anda buat linknya.
  3. Aktifkan opsi Apakah Anda ingin mengaktifkan penautan untuk intent_name?.
  4. (opsional) Di bagian Parameter kampanye, masukkan informasi yang ingin ditangkap di tautan sebagai parameter URL.
  5. (Opsional) Masukkan Judul link. Gunakan judul ini untuk mendeskripsikan fungsi Action. Sebagai misalnya, jika Action Anda mengarahkan pengguna ke alur transaksi untuk membeli tiket untuk konser, judul link Anda dapat berupa "beli tiket konser".

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

Anda dapat menguji link Asisten untuk intent apa pun (utama atau kustom, dengan atau tanpa intent 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 lainnya format font.
  3. Di perangkat yang dilengkapi dengan Asisten, login ke Asisten dengan akun yang sama yang Anda gunakan untuk membuat project Actions.
  4. Di perangkat yang sama, klik link Asisten yang dikirimkan kepada diri sendiri.

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

Secara opsional, link Asisten dapat berisi intent dan parameter di URL. Gunakan Parameter kampanye untuk menambahkan parameter kampanye.

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

  • Jika Anda tidak secara eksplisit mengaktifkan intent MAIN di link Asisten, Asisten mencocokkan intent utama tanpa parameter apa pun, mirip dengan untuk "Bicara dengan app_name".
  • Jika Anda secara eksplisit mengaktifkan intent MAIN, Asisten akan meneruskan parameter tersebut ke Actions 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 bawaan atau pengguna.
$param Nama lengkap parameter intent yang ditentukan dalam paket Action.
$value Nilai yang dienkode URL dari jenis yang dideklarasikan untuk $param dalam metode Paket Action.
$utm_param Daftar satu atau beberapa jenis parameter UTM. Nilai yang valid mencakup: 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 mencoba mengekstrak intent bawaan apa pun parameter di URL dan meneruskannya ke Action Anda. Setiap parameter yang Asisten tidak memahami karena parameter intent bawaan 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 satu parameter intent:

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 yang ditentukan oleh Action Anda sebagai bagian dari intent dan menghapus parameter lainnya.

Contoh berikut menunjukkan cara menentukan URL link Asisten yang mencakup 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 ini:

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

Parameter UTM adalah string yang dikirimkan Asisten Google ke Tindakan saat pengguna mengklik link Asisten. Anda dapat menggunakan informasi yang terdapat di {i>string<i} ini nanti untuk analitik.

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 mencakup 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 di kolom 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 lengkap memberi Anda cara untuk meningkatkan penemuan Action melalui situs Anda, dengan menggunakan help.js. Pengguna dapat mencoba Action Anda, serta menautkan Akun Google ke layanan Anda, menggunakan penautan akun.

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

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

Saat digunakan dengan penautan akun, link Rich Assistant akan menggunakan URL otorisasi Anda, yang disetel di project Anda di Konsol Actions. Untuk informasi selengkapnya, lihat dokumentasi penautan akun.

Prasyarat

Untuk menggunakan link Rich Assistant, 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, dengan mengganti <PROJECT_ID> dengan project ID Action 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 di halaman Anda. Tindakan ini akan memuat "Coba dengan Asisten Google" inline tombol:

    <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 lengkap dimulai secara otomatis saat pengguna mengunjungi halaman Anda untuk pertama kalinya, gunakan tag <google-assistant-proactive-link>. Saat Anda menerapkan tag ini, link akan aktif tanpa pengguna pada kunjungan pertama mereka, tanpa mereka memilih tombol inline.

  1. Tambahkan id ke tag grup tautan 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 setel 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 yang kaya hanya berfungsi untuk domain yang Anda miliki dan telah diverifikasi dengan Google. Saat mengembangkan secara lokal, persyaratan ini diabaikan dengan memiliki akses ke project Actions, login ke Akun Google Anda, dan menyetel 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 Anda dengan link Asisten yang lengkap:

  1. Daftarkan domain publik Anda di Konsol Actions pada Deploy > Verifikasi Merek > Hubungkan Situs.

  2. Hapus parameter kueri dev=true dari skrip:

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

Pembatasan dan praktik terbaik

Pembatasan dan praktik terbaik berikut berlaku agar URL link Asisten Anda dapat didistribusikan dan dirujuk di luar direktori tersebut atau layanan:

  • Terus dukung semua link Asisten Anda. Jika Anda mendistribusikan Link Asisten yang nantinya rusak, project Action Anda dapat ditandai sebagai tidak sehat dan hilang.

  • Memublikasikan link berarti Anda mendukung pemicuan dari sumber yang tidak tepercaya. Untuk setiap tindakan tertaut, Anda harus mengonfirmasi secara eksplisit dengan pengguna sebelum melakukan tindakan di dunia nyata. Misalnya, Action yang menonaktifkan smart home peralatan akan memberi tahu pengguna untuk mengatakan, "Yakin ingin menonaktifkan $applianceName?"

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