Link Asisten

Anda dapat membuat URL yang tertaut langsung ke intent tertentu Action Anda. Pengguna yang mengklik link Asisten (sebelumnya disebut link Action) 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 beberapa situasi yang mungkin berguna untuk link Asisten:

  • Menautkan pengguna ke petunjuk dengan panduan suara dari suatu situs petunjuk.
  • Menautkan pengguna ke pengalaman dukungan pelanggan dari halaman bantuan.
  • Menautkan pengguna ke intent update sehingga mereka dapat memilih untuk menerima 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 dalam rilis alfa Action Anda, link tersebut akan tersedia untuk penguji alfa.

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

  1. Di Konsol Actions, buka Deploy > Assistant links.
  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 apa pun yang ingin Anda ambil juga di link sebagai parameter URL.
  5. (opsional) Masukkan Judul link. Gunakan judul ini untuk menjelaskan apa yang dilakukan Action. Misalnya, jika Action Anda mengarahkan pengguna ke alur transaksi untuk membeli tiket ke konser, judul link Anda bisa saja "membeli tiket konser".

Setelah memasukkan informasi, Anda dapat melihat dan menyalin URL yang dihasilkan atau cuplikan kode yang dihasilkan 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 Anda dalam email, pesan chat, atau format lainnya.
  3. Di perangkat yang dilengkapi dengan Asisten, login ke Asisten dengan akun yang sama yang Anda gunakan untuk membuat project Action.
  4. Di perangkat yang sama, klik link Asisten yang Anda kirimkan ke diri sendiri.

Setelah mengonfirmasi bahwa link Asisten berfungsi seperti yang diharapkan, Anda harus men-deploy ulang Action untuk menyediakan link 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) dari Action Anda dengan perilaku berikut:

  • Jika Anda tidak secara eksplisit mengaktifkan intent MAIN dalam link Asisten, Asisten akan mencocokkan intent utama tanpa parameter apa pun, mirip dengan perilaku untuk "Bicara dengan app_name".
  • Jika Anda mengaktifkan intent MAIN secara eksplisit, 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 Action.
$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 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 diawali dengan actions.intent.), Asisten Google akan mencoba mengekstrak parameter intent bawaan dalam URL dan meneruskannya ke Action. 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 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 ditentukan oleh Action Anda sebagai bagian dari intent dan menghapus parameter lainnya.

Contoh berikut menunjukkan cara menentukan 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 dikirim Asisten Google ke Action Anda saat pengguna mengklik link Asisten. Anda dapat menggunakan informasi yang terkandung dalam {i>string<i} ini nanti untuk analisis.

Parameter UTM yang dikirimkan 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 Kaya memberi Anda cara untuk meningkatkan penemuan Action melalui situs, menggunakan help.js. Pengguna dapat mencoba Action Anda, serta menautkan Akun Google mereka ke layanan Anda, menggunakan penautan akun.

Saat pengguna mengunjungi situs Anda, dia akan melihat tombol "Coba dengan Asisten Google", yang memicu alur penautan Asisten Google.

Dengan mengaktifkan penautan akun untuk Action Anda, pengguna dapat mengakses Action Anda di semua perangkat yang dilengkapi dengan Asisten. Selain itu, pengguna dapat menautkan akun mereka dengan layanan Anda ke Akun Google mereka, untuk memberikan pengalaman yang lebih dipersonalisasi.

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

Prasyarat

Untuk menggunakan link Asisten 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, dengan menggantikan <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 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 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 diaktifkan tanpa pengguna pada kunjungan pertamanya, 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 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 Kaya hanya berfungsi untuk domain yang Anda miliki dan telah diverifikasi dengan Google. Saat melakukan pengembangan secara lokal, persyaratan ini dapat diabaikan dengan memiliki akses ke project Action, login ke Akun Google, 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 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:

  • Lanjutkan untuk mendukung semua link Asisten Anda. Jika Anda mendistribusikan link Asisten yang nantinya berhenti berfungsi, project Action Anda dapat ditandai sebagai tidak responsif dan dihapus.
  • Memublikasikan link berarti Anda mendukung pemicuan dari sumber yang tidak tepercaya. Untuk Action tertaut, Anda harus mengonfirmasi secara eksplisit dengan pengguna sebelum melakukan tindakan nyata apa pun. Misalnya, Action yang menonaktifkan peralatan smart home akan meminta pengguna mengucapkan, "Yakin ingin menonaktifkan $applianceName?"

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