Halaman ini menjelaskan cara membuat Add-on Google Workspace yang memungkinkan pengguna Google Dokumen, Spreadsheet, dan Slide melihat pratinjau link dari layanan pihak ketiga.
Add-on Google Workspace dapat mendeteksi link layanan Anda dan meminta pengguna 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, pengguna berinteraksi dengan smart chip dan kartu.
Saat pengguna mengetik atau menempelkan URL ke dalam dokumen, Google Dokumen akan meminta mereka untuk mengganti link dengan smart chip. Smart chip menampilkan ikon dan judul atau deskripsi singkat konten link. Saat pengguna mengarahkan kursor ke chip, mereka akan melihat antarmuka kartu yang menampilkan pratinjau informasi selengkapnya tentang file atau link.
Video berikut menunjukkan cara pengguna mengonversi link menjadi smart chip dan melihat pratinjau kartu:
Cara pengguna melihat pratinjau link di Spreadsheet dan Slide
Smart chip pihak ketiga tidak didukung untuk pratinjau link di Spreadsheet dan Slide. Saat pengguna mengetik atau menempelkan URL ke spreadsheet atau presentasi, Spreadsheet atau Slide akan meminta mereka untuk mengganti link dengan judulnya sebagai teks tertaut, bukan chip. Saat mengarahkan kursor ke judul link, pengguna akan melihat antarmuka kartu yang menampilkan pratinjau informasi tentang link tersebut.
Gambar berikut menunjukkan cara pratinjau link dirender di Spreadsheet dan Slide:
Prasyarat
Apps Script
- Akun Google Workspace.
- Add-on Google Workspace. Untuk membuat add-on, ikuti quickstart ini.
Node.js
- Akun Google Workspace.
- Add-on Google Workspace. Untuk membuat add-on, ikuti quickstart ini.
Python
- Akun Google Workspace.
- Add-on Google Workspace. Untuk membuat add-on, ikuti quickstart ini.
Java
- Akun Google Workspace.
- Add-on Google Workspace. Untuk membuat add-on, ikuti quickstart ini.
Opsional: Menyiapkan autentikasi ke layanan pihak ketiga
Jika add-on Anda terhubung ke layanan yang memerlukan otorisasi, pengguna harus melakukan autentikasi ke layanan untuk melihat pratinjau link. Artinya, saat pengguna menempelkan link dari layanan Anda ke file Dokumen, Spreadsheet, atau Slide untuk pertama kalinya, add-on Anda harus memanggil alur otorisasi.
Untuk menyiapkan layanan OAuth atau dialog otorisasi kustom, lihat salah satu panduan berikut:
Jika Anda membuat add-on menggunakan Apps Script, lihat Terhubung 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 Anda, yang mencakup langkah-langkah berikut:
- Konfigurasi pratinjau link di file manifes atau resource deployment add-on Anda.
- Buat smart chip dan antarmuka kartu untuk link Anda.
Mengonfigurasi pratinjau link
Untuk mengonfigurasi pratinjau link, tentukan bagian dan kolom berikut dalam file manifes atau resource deployment add-on Anda:
- Di bagian
addOns
, tambahkan kolomdocs
untuk memperluas Dokumen, kolomsheets
untuk memperluas Spreadsheet, dan kolomslides
untuk memperluas Slide. Di setiap kolom, implementasikan pemicu
linkPreviewTriggers
yang menyertakanrunFunction
(Anda menentukan fungsi ini di bagian berikut, Membuat smart chip 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 lain.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
berikut 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"
}
}
]
},
"sheets": {
"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"
}
}
]
},
"slides": {
"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"
}
}
]
}
}
}
Pada contoh, Add-on Google Workspace mempratinjau link untuk layanan kasus dukungan perusahaan. Add-on ini menentukan tiga pola
URL untuk melihat pratinjau link. Setiap kali link cocok dengan salah satu pola URL, fungsi callback caseLinkPreview
akan membuat dan menampilkan kartu dan smart chip, atau di Spreadsheet dan Slide, mengganti URL dengan judul link.
Membuat smart chip dan kartu
Agar dapat menampilkan smart chip dan kartu untuk link, Anda harus mengimplementasikan fungsi apa pun
yang telah ditentukan dalam objek linkPreviewTriggers
.
Saat pengguna berinteraksi dengan link yang cocok dengan pola URL yang ditentukan, pemicu linkPreviewTriggers
akan diaktifkan dan fungsi callback-nya akan meneruskan objek peristiwa EDITOR_NAME.matchedUrl.url
sebagai argumen. Anda menggunakan payload objek peristiwa ini untuk membangun smart chip dan kartu untuk pratinjau link.
Misalnya, jika pengguna melihat pratinjau link https://www.example.com/cases/123456
di Dokumen, payload peristiwa berikut akan ditampilkan:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Untuk membuat antarmuka kartu, gunakan widget untuk menampilkan informasi tentang link. 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:
- Terapkan fungsi yang Anda tentukan di bagian
linkPreviewTriggers
pada file manifes atau resource deployment add-on:- Fungsi ini harus menerima objek peristiwa yang berisi
EDITOR_NAME.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, implementasikan fungsi callback yang menyediakan interaktivitas widget untuk antarmuka. Misalnya, jika Anda menyertakan tombol yang bertuliskan "View link", Anda dapat membuat tindakan yang menentukan fungsi callback untuk membuka link di jendela baru. Untuk mempelajari interaksi widget lebih lanjut, lihat Tindakan add-on.
Kode berikut membuat fungsi callback caseLinkPreview
untuk
Dokumen:
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
bidang Kartu Layanan | Jenis |
---|---|
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 ) |
Jenis |
---|---|
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 dengan pratinjau link ke kasus dukungan perusahaan di Google Dokumen.
Contoh tersebut melakukan hal berikut:
- Melihat pratinjau link ke kasus dukungan, seperti
https://www.example.com/support/cases/1234
. Smart chip menampilkan ikon dukungan, dan kartu pratinjau menyertakan ID kasus serta deskripsi. - Jika lokalitas pengguna disetel ke bahasa Spanyol, smart chip akan melokalkan
labelText
ke bahasa Spanyol.
Resource deployment
Apps Script
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-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"
}
]
}
}
}
Kode
Apps Script
Node.js
Python
Java
Referensi terkait
- Melihat pratinjau link dari Google Buku dengan smart chip
- Menguji add-on
- Resource deployment Google Dokumen
- Antarmuka kartu untuk pratinjau link