Manifes untuk add-on Google Workspace

Add-on menggunakan file manifest untuk mengonfigurasi detail tertentu tentang aplikasi dan operasinya.

Dokumentasi ini mencakup detail konfigurasi file manifes untuk Add-on Google Workspace.

Struktur file 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 disusun di bagian addOns dari struktur objek manifes.

  • Untuk mengetahui informasi tentang file manifes Apps Script, lihat Struktur manifes.

  • Untuk mengetahui informasi tentang file manifes untuk add-on yang dibuat dengan endpoint HTTP, lihat resource projects.deployments.

Manifest untuk Google Chat

Jika add-on Google Workspace Anda memperluas Google Chat, Anda harus mengonfigurasi aplikasi Google Chat dengan mengaktifkan dan mengonfigurasi Google Chat API di konsol Google Cloud.

Setelan konfigurasi manifes umum (termasuk addons.common) diabaikan di Chat. Daripada menggunakan manifes add-on, Anda menggunakan Chat API untuk mengonfigurasi setelan Chat berikut:

Jika Anda telah membuat add-on di Apps Script, Anda juga harus menambahkan atau memperbarui objek berikut di manifes Anda:

Untuk mengetahui langkah-langkah mengonfigurasi setelan Chat untuk add-on, lihat Mengonfigurasi aplikasi Google Chat.

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 independen dari 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 mengaktifkan hal berikut:

    • Pemicu Kalender eventOpen dan eventUpdated.

    • (Khusus Apps Script) Dua solusi konferensi Kalender.

    • Dua tindakan universal.

    • A Drive onItemsSelectedTrigger.

    • Tindakan penulisan Gmail dan pemicu kontekstual.

    • Objek linkPreviewTriggersDokumen. 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.

    • (Khusus HTTP) Dua HttpOptions untuk mengirim header otorisasi dan mendukung izin terperinci.

  • 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 Memberi izin URL.

Link dalam contoh manifes mengalihkan 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"
      }
    }
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "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 daftar yang diizinkan

Anda menggunakan daftar yang diizinkan untuk menetapkan 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 belum ditambahkan ke daftar yang diizinkan.

Kolom ini bersifat opsional saat Anda menginstal deployment pengujian, tetapi wajib diisi saat Anda membuat deployment versi.

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

  • Mengambil atau mem-fetch informasi dari lokasi eksternal (seperti endpoint HTTPS) menggunakan layanan UrlFetch Apps Script. Untuk memasukkan URL ke daftar yang diizinkan untuk 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 bagi Google). Untuk memasukkan URL dalam daftar yang diizinkan untuk dibuka, sertakan kolom addOns.common.openLinkUrlPrefixes dalam file manifes Anda.

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 membuat data pengguna berisiko dan dapat memperpanjang proses peninjauan add-on. Gunakan karakter pengganti hanya jika fungsi add-on Anda memerlukannya.

Saat menentukan apakah URL cocok dengan awalan dalam daftar yang diizinkan, aturan berikut berlaku:

  • Pencocokan jalur peka huruf besar/kecil.
  • Jika awalan sama dengan URL, maka itu adalah kecocokan.
  • Jika URL sama atau merupakan turunan dari awalan, maka 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 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 saat Anda mencoba menyimpan:

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