Manifes untuk Add-on Google Workspace

Project Apps Script menggunakan file manifes untuk mengonfigurasi detail tertentu tentang skrip dan operasinya. Untuk mempelajari cara melihat dan mengedit manifes, lihat Manifes.

Dokumentasi ini membahas detail konfigurasi manifes untuk add-on Google Workspace.

Struktur manifes untuk Add-on Google Workspace

Add-on Google Workspace menggunakan file manifes project Apps Script untuk menentukan beberapa aspek tampilan dan perilaku add-on. Properti manifes untuk Add-on Google Workspace diatur dalam bagian addOns dari struktur objek manifes.

Contoh konfigurasi manifes Add-on Google Workspace

Contoh manifes berikut menunjukkan bagian file manifes yang menentukan Add-on Google Workspace, termasuk aspek berikut:

• Bagian addOns.common dari manifes menentukan nama, URL logo, warna, dan setelan umum lainnya yang tidak bergantung pada host untuk add-on tersebut.
• Manifes menentukan halaman beranda umum, tetapi juga menentukan halaman beranda khusus Kalender, Drive, Dokumen, Spreadsheet, dan Slide. Gmail menggunakan halaman beranda default.
• Contoh setelan manifes memungkinkan hal berikut:
  • Pemicu Kalender eventOpen dan eventUpdated, serta dua solusi konferensi Kalender.
  • Dua tindakan universal.
  • Drive onItemsSelectedTrigger.
  • Tindakan Compose dan pemicu kontekstual Gmail.
  • linkPreviewTrigger Dokumen. Untuk mempelajari pemicu ini, lihat Melihat pratinjau link dengan chip pintar.
  • Antarmuka khusus file untuk Dokumen, Spreadsheet, dan Slide.
• Kolom oauthScopes menetapkan cakupan otorisasi untuk project (Biasanya diperlukan untuk add-on).
• Kolom urlFetchWhitelist adalah kolom yang memastikan bahwa endpoint yang diambil cocok dengan daftar awalan URL HTTPS yang ditentukan. Kolom ini bersifat opsional untuk deployment pengujian, tetapi wajib untuk deployment. Untuk informasi selengkapnya, lihat URL daftar yang diizinkan.

Link dalam contoh mengarah langsung ke deskripsi kolom tersebut di dokumentasi referensi manifes.

Catatan: Manifes menyertakan komponen lain yang terkait dengan properti Apps Script. Kolom di bawah kolom addOns ini berkaitan langsung dengan Add-on Google Workspace. Contoh ini hanyalah sebagian dari file manifes lengkap dan bukan manifes yang berfungsi sepenuhnya.

// Sample configuration of the addOns section in a manifest file:
{
  "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://en.wikipedia.org/wiki/",
        "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"
        }
      ]
    },

    "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/"
  ],
}

URL Daftar yang Diizinkan

Anda menggunakan daftar yang diizinkan untuk menentukan URL tertentu yang telah disetujui sebelumnya untuk diakses oleh skrip atau add-on Anda. Daftar yang diizinkan membantu melindungi data pengguna; saat Anda menentukan daftar yang diizinkan, project skrip tidak dapat mengakses URL yang tidak diizinkan.

Anda menggunakan daftar yang diizinkan saat skrip atau add-on melakukan tindakan berikut:

• Mengambil atau mengambil informasi dari lokasi eksternal (seperti endpoint HTTPS) menggunakan layanan UrlFetch Apps Script. Untuk mengizinkan pengambilan URL, sertakan kolom urlFetchWhitelist di file manifes Anda.
• Membuka atau menampilkan URL sebagai respons terhadap tindakan pengguna (Diperlukan untuk Add-on Google Workspace yang membuka atau menampilkan URL yang berada di luar Google). Untuk mengizinkan URL yang dibuka, sertakan kolom addOns.common.openLinkUrlPrefixes di file manifes Anda.

Catatan: Daftar yang diizinkan, seperti yang digunakan di urlFetchWhitelist, adalah istilah yang tidak digunakan lagi yang identik dan diganti dengan daftar yang diizinkan. Untuk informasi selengkapnya, lihat Menulis dokumentasi inklusif.

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://, bukan http://.
• Setiap awalan harus memiliki domain lengkap.
• Setiap awalan harus memiliki jalur yang tidak kosong. Misalnya, https://www.google.com/ valid, tetapi https://www.google.com tidak valid.
• Anda dapat menggunakan karakter pengganti untuk mencocokkan awalan subdomain URL.
• Satu karakter pengganti * dapat digunakan di kolom addOns.common.openLinkUrlPrefixes untuk mencocokkan semua link, tetapi tindakan ini tidak direkomendasikan karena dapat mengekspos risiko pengguna 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 berlaku:

• Pencocokan jalur peka huruf besar/kecil.
• Jika awalan identik dengan URL, berarti cocok.
• Jika URL sama atau turunan dari awalan, URL akan 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 karakter pengganti tunggal (*) untuk mencocokkan subdomain bagi 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 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 harus ada satu subdomain)

Beberapa aturan awalan diterapkan saat Anda mencoba menyimpan manifes. Misalnya, awalan berikut menyebabkan error jika ada dalam manifes Anda saat Anda mencoba menyimpan:

• https://*.*.example.com/foo (beberapa karakter pengganti dilarang)
• https://subdomain.*.example.com/foo (karakter pengganti harus digunakan sebagai awalan di awal)