Manifes untuk Add-on Google Workspace

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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 cara mengonfigurasi 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 di bagian addOns struktur objek manifes.

Contoh konfigurasi manifes Add-on Google Workspace

Contoh manifes di bawah ini 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.
  • Manifes menentukan halaman beranda umum, tetapi juga menentukan halaman beranda khusus Kalender, Drive, Dokumen, Spreadsheet, dan Slide. Gmail menggunakan halaman beranda default.
  • Setelan manifes sampel memungkinkan hal berikut:
    • Pemicu Kalender eventOpen dan eventUpdated, serta dua solusi konferensi Kalender.
    • Dua tindakan universal.
    • Drive onItemsSelectedTrigger.
    • Tindakan tulis Gmail dan pemicu kontekstual.
    • Antarmuka khusus file untuk Dokumen, Spreadsheet, dan Slide.
  • Kolom oauthScopes menetapkan cakupan otorisasi untuk project (Biasanya diperlukan untuk add-on).
  • Kolom urlFetchWhitelist menetapkan awalan URL HTTPS, yang memastikan bahwa endpoint yang diambil cocok dengan awalan (Biasanya diperlukan untuk add-on). Untuk informasi selengkapnya, lihat URL daftar yang diizinkan.

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

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

    "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"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
}

URL yang diizinkan

Terkadang, Anda mungkin ingin skrip atau add-on membuka URL sebagai respons terhadap tindakan pengguna. Terkadang, Anda mungkin ingin skrip atau add-on mengambil informasi dari lokasi eksternal menggunakan layanan UrlFetch Apps Script. Dalam kedua kasus tersebut, Anda harus mengizinkan URL yang Anda buka atau ambil di manifes project.

Pemberian izin adalah proses saat Anda menentukan URL tertentu yang telah disetujui sebelumnya untuk diakses oleh skrip atau add-on. Persyaratan ini membantu melindungi data pengguna; jika Anda menentukan daftar yang diizinkan, project skrip tidak dapat mengakses URL yang tidak diizinkan. Google Workspace add-on memerlukan URL yang diizinkan sebelum dapat diambil atau dibuka.

Anda dapat mengizinkan URL untuk mengambil dengan menambahkannya atau awalan yang cocok ke kolom manifes urlFetchWhitelist. Untuk Google Workspace project add-on, Anda dapat mengizinkan URL untuk dibuka dengan menambahkannya atau awalan yang cocok ke kolom manifes addOns.common.openLinkUrlPrefixes.

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. Namun, hal ini tidak direkomendasikan karena dapat membahayakan data pengguna dan dapat memperpanjang proses peninjauan add-on. Hanya gunakan karakter pengganti jika fungsionalitas 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, berarti awalannya cocok.
  • Jika URL sama atau turunan dari awalan, berarti URL 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 karakter pengganti tunggal (*) untuk mencocokkan subdomain baik untuk kolom urlFetchWhitelist maupun addOns.common.openLinkUrlPrefixes. Anda tidak dapat menggunakan lebih dari satu karakter pengganti untuk mencocokkan beberapa subdomain, dan karakter pengganti harus mewakili awalan URL yang utama.

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)