Add-on menggunakan file manifes untuk mengonfigurasi detail tertentu tentang aplikasi dan operasinya.
Dokumentasi ini membahas detail cara mengonfigurasi manifes untuk Add-on Google Workspace.
Struktur manifes untuk Add-on Google Workspace
Add-on Google Workspace menggunakan file manifes untuk menentukan beberapa aspek tampilan dan perilaku add-on.
Properti manifes untuk Add-on Google Workspace diatur di bagian addOns
dari struktur objek manifes.
- Untuk mengetahui informasi tentang file manifes Apps Script, lihat Struktur manifes.
- Guna mengetahui informasi tentang file manifes untuk add-on yang di-build dengan endpoint HTTP, lihat Resource REST:
projects.deployments
Contoh konfigurasi manifes Add-on Google Workspace
Contoh manifes berikut menunjukkan bagian file manifes yang menentukan Add-on Google Workspace, termasuk aspek-aspek berikut:
- Bagian
addOns.common
pada manifes menentukan nama, URL logo, warna, dan setelan umum lainnya yang tidak bergantung pada host untuk add-on. - Manifes menentukan halaman beranda umum, tetapi juga menentukan halaman beranda khusus Kalender, Drive, Dokumen, Spreadsheet, dan Slide. Gmail menggunakan halaman beranda default.
- Setelan manifes contoh memungkinkan hal berikut:
- Pemicu Kalender
eventOpen
daneventUpdated
. - (Khusus Apps Script) Dua solusi konferensi Kalender.
- Dua tindakan universal.
- Drive
onItemsSelectedTrigger
. - Tindakan penulisan dan pemicu kontekstual Gmail.
- Objek
linkPreviewTriggers
Dokumen. Untuk mempelajari pemicu ini, lihat Melihat pratinjau link dengan smart chip. - Objek
createActionTriggers
Dokumen. Untuk mempelajari pemicu ini, lihat Membuat resource pihak ketiga dari menu @. - Antarmuka khusus file untuk Dokumen, Spreadsheet, dan Slide.
- Pemicu Kalender
- Kolom
oauthScopes
menetapkan cakupan otorisasi untuk project (Biasanya diperlukan untuk add-on). - (Khusus Apps Script) Kolom
urlFetchWhitelist
adalah kolom yang memastikan bahwa setiap endpoint yang diambil cocok dengan daftar awalan URL HTTPS yang ditentukan. Untuk mengetahui informasi selengkapnya, lihat Daftar URL yang diizinkan.
Link dalam contoh mengarah ke deskripsi kolom tersebut dalam dokumentasi referensi manifes yang sesuai untuk Add-on Google Workspace Apps Script dan HTTP.
Apps Script
{ "addOns": { "calendar": { "createSettingsUrlFunction": "getConferenceSettingsPageUrl", "conferenceSolution": [{ "id": "my-video-conf", "logoUrl": "https://lh3.googleusercontent.com/...", "name": "My Video Conference", "onCreateFunction": "onCreateMyVideoConference" }, { "id": "my-streamed-conf", "logoUrl": "https://lh3.googleusercontent.com/...", "name": "My Streamed Conference", "onCreateFunction": "onCreateMyStreamedConference" }], "currentEventAccess": "READ_WRITE", "eventOpenTrigger": { "runFunction": "onCalendarEventOpen" }, "eventUpdateTrigger": { "runFunction": "onCalendarEventUpdate" }, "eventAttachmentTrigger": { "label": "My Event Attachment", "runFunction": "onCalendarEventAddAttachment" }, "homepageTrigger": { "runFunction": "onCalendarHomePageOpen", "enabled": true } }, "common": { "homepageTrigger": { "runFunction": "onDefaultHomePageOpen", "enabled": true }, "layoutProperties": { "primaryColor": "#ff392b", "secondaryColor": "#d68617" }, "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png", "name": "Demo Google Workspace Add-on", "openLinkUrlPrefixes": [ "https://mail.google.com/", "https://script.google.com/a/google.com/d/", "https://drive.google.com/a/google.com/file/d/", "https://www.example.com/" ], "universalActions": [{ "label": "Open settings", "runFunction": "getSettingsCard" }, { "label": "Open Help URL", "openLink": "https://www.example.com/help" }], "useLocaleFromApp": true }, "drive": { "homepageTrigger": { "runFunction": "onDriveHomePageOpen", "enabled": true }, "onItemsSelectedTrigger": { "runFunction": "onDriveItemsSelected" } }, "gmail": { "composeTrigger": { "selectActions": [ { "text": "Add images to email", "runFunction": "getInsertImageComposeCards" } ], "draftAccess": "METADATA" }, "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "onGmailMessageOpen" } ] }, "docs": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" }, "linkPreviewTriggers": [ { "runFunction": "onLinkPreview", "patterns": [ { "hostPattern": "example.com", "pathPrefix": "example-path" } ], "labelText": "Link preview", "localizedLabelText": { "es": "Link preview localized in Spanish" }, "logoUrl": "https://www.example.com/images/smart-chip-icon.png" } ], "createActionTriggers": [ { "id": "exampleId", "labelText": "Example label text", "localizedLabelText": { "es": "Label text localized in Spanish" }, "runFunction": "exampleFunction", "logoUrl": "https://www.example.com/images/case.png" } ] }, "sheets": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" } }, "slides": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" } } }, "oauthScopes": [ "https://www.googleapis.com/auth/calendar.addons.execute", "https://www.googleapis.com/auth/calendar.addons.current.event.read", "https://www.googleapis.com/auth/calendar.addons.current.event.write", "https://www.googleapis.com/auth/drive.addons.metadata.readonly", "https://www.googleapis.com/auth/gmail.addons.current.action.compose", "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/script.external_request", "https://www.googleapis.com/auth/script.locale", "https://www.googleapis.com/auth/script.scriptapp", "https://www.googleapis.com/auth/drive.file", "https://www.googleapis.com/auth/documents.currentonly", "https://www.googleapis.com/auth/spreadsheets.currentonly", "https://www.googleapis.com/auth/presentations.currentonly", "https://www.googleapis.com/auth/workspace.linkpreview" ], "urlFetchWhitelist": [ "https://www.example.com/myendpoint/" ] }
HTTP
{ "addOns": { "calendar": { "currentEventAccess": "READ_WRITE", "eventOpenTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen" }, "eventUpdateTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate" }, "eventAttachmentTrigger": { "label": "My Event Attachment", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment" }, "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen", "enabled": true } }, "common": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDefaultHomePageOpen", "enabled": true }, "layoutProperties": { "primaryColor": "#ff392b", "secondaryColor": "#d68617" }, "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png", "name": "Demo Google Workspace Add-on", "openLinkUrlPrefixes": [ "https://mail.google.com/", "https://script.google.com/a/google.com/d/", "https://drive.google.com/a/google.com/file/d/", "https://www.example.com/" ], "universalActions": [{ "label": "Open settings", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard" }, { "label": "Open Help URL", "openLink": "https://www.example.com/help" }], "useLocaleFromApp": true }, "drive": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen", "enabled": true }, "onItemsSelectedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected" } }, "gmail": { "composeTrigger": { "actions": [ { "label": "Add images to email", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards" } ], "draftAccess": "METADATA" }, "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen" } ] }, "docs": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors" }, "linkPreviewTriggers": [ { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onLinkPreview", "patterns": [ { "hostPattern": "example.com", "pathPrefix": "example-path" } ], "labelText": "Link preview", "localizedLabelText": { "es": "Link preview localized in Spanish" }, "logoUrl": "https://www.example.com/images/smart-chip-icon.png" } ], "createActionTriggers": [ { "id": "exampleId", "labelText": "Example label text", "localizedLabelText": { "es": "Label text localized in Spanish" }, "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction", "logoUrl": "https://www.example.com/images/case.png" } ] }, "sheets": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors" } }, "slides": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors" } } }, "oauthScopes": [ "https://www.googleapis.com/auth/calendar.addons.execute", "https://www.googleapis.com/auth/calendar.addons.current.event.read", "https://www.googleapis.com/auth/calendar.addons.current.event.write", "https://www.googleapis.com/auth/drive.addons.metadata.readonly", "https://www.googleapis.com/auth/gmail.addons.current.action.compose", "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/script.external_request", "https://www.googleapis.com/auth/script.locale", "https://www.googleapis.com/auth/script.scriptapp", "https://www.googleapis.com/auth/drive.file", "https://www.googleapis.com/auth/documents.currentonly", "https://www.googleapis.com/auth/spreadsheets.currentonly", "https://www.googleapis.com/auth/presentations.currentonly", "https://www.googleapis.com/auth/workspace.linkpreview" ] }
Daftar URL yang diizinkan
Anda menggunakan daftar yang diizinkan untuk menentukan URL tertentu yang telah disetujui sebelumnya untuk akses oleh skrip atau add-on Anda. Daftar yang diizinkan membantu melindungi data pengguna. Jika Anda menentukan daftar yang diizinkan, project skrip tidak dapat mengakses URL yang belum diizinkan.
Kolom ini bersifat opsional saat Anda menginstal deployment pengujian, tetapi wajib diisi saat Anda membuat deployment berversi.
Anda akan menggunakan daftar yang diizinkan saat skrip atau add-on melakukan tindakan berikut:
- Mengambil atau mengambil informasi dari lokasi eksternal (seperti endpoint
HTTPS) menggunakan layanan
Apps Script
UrlFetch
. Untuk mengizinkan URL untuk pengambilan, sertakan kolomurlFetchWhitelist
di file manifes Anda. - Membuka atau menampilkan URL sebagai respons atas tindakan pengguna (Diperlukan untuk
Add-on Google Workspace yang membuka atau menampilkan URL yang eksternal bagi
Google). Untuk mengizinkan URL dibuka, sertakan kolom
addOns.common.openLinkUrlPrefixes
dalam file manifes Anda.
Menambahkan awalan ke daftar yang diizinkan
Saat menentukan daftar yang diizinkan di file manifes (dengan menyertakan kolom addOns.common.openLinkUrlPrefixes
atau urlFetchWhitelist
), Anda harus menyertakan daftar awalan URL. Awalan yang Anda tambahkan ke manifes harus memenuhi persyaratan berikut:
- Setiap awalan harus berupa URL yang valid.
- Setiap awalan harus menggunakan
https://
, bukanhttp://
. - Setiap awalan harus memiliki domain lengkap.
- Setiap awalan harus memiliki jalur yang tidak kosong. Misalnya,
https://www.google.com/
valid, tetapihttps://www.google.com
tidak. - Anda dapat menggunakan karakter pengganti untuk mencocokkan awalan subdomain URL.
- Karakter pengganti
*
tunggal dapat digunakan di kolomaddOns.common.openLinkUrlPrefixes
untuk mencocokkan semua link, tetapi hal ini tidak direkomendasikan karena dapat mengekspos data pengguna terhadap risiko dan dapat memperpanjang proses peninjauan add-on. Hanya gunakan karakter pengganti jika fungsi add-on Anda memerlukannya.
Saat menentukan apakah URL cocok dengan awalan yang diizinkan, aturan berikut akan berlaku:
- Pencocokan jalur peka huruf besar/kecil.
- Jika awalan identik dengan URL, awalan tersebut cocok.
- Jika URL sama atau turunan dari awalan, URL tersebut cocok.
Misalnya, awalan https://example.com/foo
cocok dengan URL berikut:
https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar
Menggunakan karakter pengganti
Anda dapat menggunakan satu karakter pengganti (*
) untuk mencocokkan subdomain
untuk kolom
urlFetchWhitelist
dan addOns.common.openLinkUrlPrefixes
. Anda tidak dapat menggunakan lebih dari satu karakter pengganti untuk mencocokkan beberapa subdomain, dan karakter pengganti harus mewakili awalan di awal URL.
Misalnya, awalan https://*.example.com/foo
cocok dengan URL
berikut:
https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo
Awalan https://*.example.com/foo
tidak cocok dengan URL
berikut:
https://subdomain.example.com/bar
(akhiran tidak cocok)https://example.com/foo
(setidaknya satu subdomain harus ada)
Beberapa aturan awalan diterapkan saat Anda mencoba menyimpan manifes. Misalnya, awalan berikut menyebabkan error jika ada dalam manifes Anda saat mencoba menyimpan:
https://*.*.example.com/foo
(beberapa karakter pengganti dilarang)https://subdomain.*.example.com/foo
(karakter pengganti harus digunakan sebagai awalan di awal)