Halaman ini menjelaskan cara membuat Add-on Google Workspace yang memungkinkan pengguna Google Dokumen melihat pratinjau link dari layanan pihak ketiga.
Add-on Google Workspace dapat mendeteksi link layanan dan meminta pengguna Google Dokumen untuk melihat pratinjaunya. Anda dapat mengonfigurasi add-on untuk melihat pratinjau beberapa pola URL, seperti link ke kasus dukungan, prospek penjualan, dan profil karyawan.
Cara pengguna melihat pratinjau link
Untuk melihat pratinjau link dalam dokumen Google Dokumen, pengguna berinteraksi dengan chip pintar dan kartu:
Saat pengguna mengetik atau menempelkan URL ke dalam dokumen, Google Dokumen akan meminta mereka untuk mengganti link dengan chip pintar. Chip pintar menampilkan ikon dan judul atau deskripsi singkat untuk konten link. Saat pengguna mengarahkan kursor ke chip, mereka akan melihat antarmuka kartu yang melihat pratinjau informasi selengkapnya tentang file atau link.
Video berikut menunjukkan cara pengguna mengonversi link menjadi chip pintar dan melihat pratinjau kartu:
Prasyarat
Apps Script
- Akun Google Workspace.
- Add-on Google Workspace. Untuk membuat add-on, ikuti panduan memulai ini.
Node.js
- Akun Google Workspace.
- Add-on Google Workspace. Untuk membuat add-on, ikuti panduan memulai ini.
Python
- Akun Google Workspace.
- Add-on Google Workspace. Untuk membuat add-on, ikuti panduan memulai ini.
Java
- Akun Google Workspace.
- Add-on Google Workspace. Untuk membuat add-on, ikuti panduan memulai ini.
Opsional: Menyiapkan autentikasi ke layanan pihak ketiga
Jika add-on terhubung ke layanan yang memerlukan otorisasi, pengguna harus mengautentikasi ke layanan untuk melihat pratinjau link. Artinya, saat pengguna menempelkan link dari layanan Anda ke dokumen Google Dokumen untuk pertama kalinya, add-on Anda harus memanggil alur otorisasi.
Untuk menyiapkan layanan OAuth atau permintaan otorisasi kustom, lihat salah satu panduan berikut:
Jika Anda membuat add-on menggunakan Apps Script, lihat Menghubungkan ke Layanan non-Google dari Add-on Google Workspace.
Jika Anda membuat add-on menggunakan runtime yang berbeda, lihat Menghubungkan add-on ke layanan pihak ketiga.
Menyiapkan pratinjau link untuk add-on
Bagian ini menjelaskan cara menyiapkan pratinjau link untuk add-on, yang mencakup langkah-langkah berikut:
- Konfigurasikan pratinjau link di resource deployment atau file manifes add-on.
- Buat chip pintar dan antarmuka kartu untuk link Anda.
Mengonfigurasi pratinjau link
Untuk mengonfigurasi pratinjau link, tentukan bagian dan kolom berikut di resource deployment atau file manifes add-on:
- Di bagian
addOns
, tambahkan kolomdocs
untuk memperluas Google Dokumen. Di kolom
docs
, terapkan pemiculinkPreviewTriggers
yang menyertakanrunFunction
(Anda menentukan fungsi ini di bagian berikut, Mem-build chip pintar dan kartu).Untuk mempelajari kolom yang dapat Anda tentukan dalam pemicu
linkPreviewTriggers
, lihat dokumentasi referensi untuk file manifes Apps Script atau resource deployment untuk runtime lainnya.Di kolom
oauthScopes
, tambahkan cakupanhttps://www.googleapis.com/auth/workspace.linkpreview
sehingga pengguna dapat mengizinkan add-on untuk melihat pratinjau link atas nama mereka.
Sebagai contoh, lihat bagian oauthScopes
dan addons
dari resource deployment yang mengonfigurasi pratinjau link untuk layanan kasus dukungan:
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://www.example.com/images/company-logo.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
}
}
}
Dalam contoh tersebut, link Pratinjau Add-on Google Workspace untuk layanan kasus dukungan perusahaan. Add-on menentukan tiga pola
URL untuk melihat pratinjau link. Setiap kali link cocok dengan salah satu pola URL di
dokumen Google Dokumen, fungsi callback caseLinkPreview
akan mem-build dan
menampilkan smart chip dan kartu.
Membuat chip dan kartu smart
Untuk menampilkan chip dan kartu smart untuk link, Anda harus mengimplementasikan fungsi apa pun
yang Anda tentukan dalam objek linkPreviewTriggers
.
Saat pengguna berinteraksi dengan link yang cocok dengan pola URL yang ditentukan, pemicu linkPreviewTriggers
akan aktif dan fungsi callback-nya meneruskan objek peristiwa docs.matchedUrl.url
sebagai argumen. Anda menggunakan payload objek peristiwa ini untuk mem-build smart chip dan kartu untuk pratinjau link.
Misalnya, untuk add-on yang menentukan pola URL example.com/cases
, jika pengguna melihat pratinjau link https://www.example.com/cases/123456
, payload peristiwa berikut akan ditampilkan:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Untuk membuat antarmuka kartu, Anda menggunakan widget untuk menampilkan informasi tentang link tersebut. Anda juga dapat membuat tindakan yang memungkinkan pengguna membuka link atau mengubah kontennya. Untuk daftar widget dan tindakan yang tersedia, lihat Komponen yang didukung untuk kartu pratinjau.
Untuk membuat smart chip dan kartu untuk pratinjau link:
- Implementasikan fungsi yang Anda tentukan di bagian
linkPreviewTriggers
pada resource deployment atau file manifes add-on:- Fungsi ini harus menerima objek peristiwa yang berisi
docs.matchedUrl.url
sebagai argumen dan menampilkan satu objekCard
. - Jika layanan Anda memerlukan otorisasi, fungsi tersebut juga harus memanggil alur otorisasi.
- Fungsi ini harus menerima objek peristiwa yang berisi
- Untuk setiap kartu pratinjau, terapkan fungsi callback yang digunakan untuk memberikan
interaktivitas widget untuk antarmuka. Misalnya, jika Anda menyertakan tombol
di antarmuka, tombol tersebut harus memiliki
Action
yang dilampirkan dan fungsi callback yang diimplementasikan yang berjalan saat tombol diklik.
Kode berikut membuat fungsi callback caseLinkPreview
:
Apps Script
Node.js
Python
Java
Komponen yang didukung untuk kartu pratinjau
Add-on Google Workspace mendukung widget dan tindakan berikut untuk kartu pratinjau link:
Apps Script
Kolom Card Card | Type |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
IconImage |
Widget |
ButtonSet |
Widget |
TextButton |
Widget |
ImageButton |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Tindakan |
Navigation |
Tindakan Hanya metode updateCard yang didukung. |
JSON
Kolom kartu (google.apps.card.v1 ) |
Type |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
Icon |
Widget |
ButtonList |
Widget |
Button |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Tindakan |
Navigation |
Tindakan Hanya metode updateCard yang didukung. |
Contoh lengkap: Add-on kasus dukungan
Contoh berikut menampilkan Add-on Google Workspace yang mempratinjau link ke kasus dukungan dan profil karyawan perusahaan.
Contoh berikut:
- Link pratinjau ke kasus dukungan, seperti
https://www.example.com/support/cases/1234
. Chip pintar menampilkan ikon dukungan, dan kartu pratinjau menyertakan ID kasus serta deskripsi. - Melihat pratinjau link ke agen kasus dukungan, seperti
https://www.example.com/people/rosario-cruz
. Chip pintar menampilkan ikon orang, dan kartu pratinjau mencakup nama, email, jabatan, dan foto profil karyawan. - Jika lokalitas pengguna disetel ke bahasa Spanyol, chip pintar akan melokalkan
labelText
ke bahasa Spanyol.
Resource Deployment
Apps Script
{
"timeZone": "America/New_York",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "peopleLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}