Manifes untuk Add-on Google Workspace

Add-on menggunakan file manifes untuk mengkonfigurasi detail tertentu tentang aplikasi dan operasinya.

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 untuk menentukan beberapa aspek add-on penampilan dan perilaku pengguna.

Properti manifes untuk Add-on Google Workspace diatur di bagian addOns dalam 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:

  • addOns.common manifes mendefinisikan nama, URL logo, warna, dan setelan umum yang tidak bergantung pada host untuk add-on.
  • Manifes mendefinisikan halaman beranda umum, tetapi juga mendefinisikan Kalender, Drive, Dokumen, Halaman beranda khusus Spreadsheet, dan Slide. Gmail menggunakan halaman beranda default.
  • Setelan manifes contoh memungkinkan hal berikut:
  • Kolom oauthScopes menetapkan cakupan otorisasi untuk project (Biasanya diperlukan untuk add-on).
  • (Khusus Apps Script) urlFetchWhitelist adalah kolom yang memastikan bahwa setiap endpoint yang diambil cocok dengan daftar awalan URL HTTPS. Untuk 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"
  ]
}

URL yang Diizinkan

Anda menggunakan daftar yang diizinkan untuk menetapkan URL tertentu yang telah disetujui sebelumnya untuk akses 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 belum ditambahkan ke daftar yang diizinkan.

Kolom ini bersifat opsional saat Anda menginstal deployment pengujian, tetapi diperlukan saat Anda membuat deployment dengan versi.

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

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

Menambahkan awalan ke daftar yang diizinkan

Saat menentukan daftar yang diizinkan dalam 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.
  • 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 hal ini tidak direkomendasikan karena dapat mengekspos data pengguna ke 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 dalam daftar yang diizinkan, aturan berikut terapkan:

  • Pencocokan jalur peka huruf besar/kecil.
  • Jika awalan sama dengan URL, berarti 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 baik urlFetchWhitelist dan addOns.common.openLinkUrlPrefixes kolom. Anda tidak dapat menggunakan lebih dari satu karakter pengganti untuk mencocokkan beberapa subdomain, dan karakter pengganti harus mewakili awalan URL yang diawali.

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. Sebagai contoh, awalan berikut menyebabkan error jika ada di manifes 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)