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 mengarahkan kursor ke chip, pengguna 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 developer pratinjau link di Spreadsheet dan Slide. Saat pengguna mengetik atau menempel 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 untuk layanan pihak ketiga
Jika add-on 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 permintaan 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 mem-build 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:
- Konfigurasi pratinjau link di file manifes atau resource deployment add-on Anda.
- Buat antarmuka smart chip dan kartu untuk link Anda.
Mengonfigurasi pratinjau link
Untuk mengonfigurasi pratinjau link, tentukan bagian dan kolom berikut di 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
agar 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"
}
}
]
}
}
}
Dalam 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, akan 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 Anda tentukan dalam objek linkPreviewTriggers
.
Saat pengguna berinteraksi dengan link yang cocok dengan pola URL tertentu, 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 mem-build smart chip dan kartu untuk
pratinjau link.
Misalnya, untuk add-on yang menentukan pola URL example.com/cases
untuk Dokumen, 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. 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 Anda:- 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, terapkan fungsi callback yang menyediakan interaktivitas widget untuk antarmuka. Misalnya, jika 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 Card Service | 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 yang mempratinjau link ke kasus dukungan perusahaan dan profil karyawan 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. - Melihat pratinjau link ke agen kasus dukungan, seperti
https://www.example.com/people/rosario-cruz
. Smart chip menampilkan ikon orang, dan kartu pratinjau berisi nama, email, jabatan, dan foto profil karyawan. - 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/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"
}
]
}
}
}
Code
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