Manifest per i componenti aggiuntivi di Google Workspace

Un componente aggiuntivo utilizza un file manifest per configurare determinati dettagli sull'app e sul suo funzionamento.

Questa documentazione descrive i dettagli della configurazione di un manifest per un componente aggiuntivo di Google Workspace.

Struttura del manifest per i componenti aggiuntivi di Google Workspace

I componenti aggiuntivi di Google Workspace utilizzano il file manifest per definire diversi aspetti dell'aspetto e del comportamento.

Le proprietà del file manifest per i componenti aggiuntivi di Google Workspace sono organizzate nella sezione addOns.

Per informazioni sui file manifest di Google Apps Script, consulta Struttura del manifest.
Per informazioni sui file manifest per i componenti aggiuntivi creati con endpoint HTTP, consulta projects.deployments.

Manifest per Google Chat

Se il tuo componente aggiuntivo di Google Workspace estende Google Chat, configura un'app di Google Chat attivando e configurando l'API Google Chat nella console Google Cloud.

Le impostazioni di configurazione comuni del file manifest (incluso addons.common) vengono ignorate in Chat. Utilizza l'API Chat per configurare le seguenti impostazioni di Chat:

Il nome, il logo e la descrizione dell'app Chat per l'interfaccia utente di Chat.
Trigger dell'app di chat.

Se hai creato il componente aggiuntivo in Apps Script, aggiungi o aggiorna i seguenti oggetti nel manifest:

addons.chat (obbligatorio)
oauthScopes (obbligatorio se la tua app Google Chat utilizza OAuth)

Per configurare le impostazioni di Chat per un componente aggiuntivo, vedi Configurare un'app Google Chat.

Esempio di configurazione del file manifest del componente aggiuntivo di Google Workspace

I seguenti esempi mostrano la parte di un manifest che definisce un componente aggiuntivo Google Workspace, inclusi questi aspetti:

addOns.common definisce il nome, il logo, i colori e altre impostazioni generali del componente aggiuntivo.
Il manifest definisce una home page comune, ma anche home page specifiche per Google Calendar, Google Drive, Documenti Google, Fogli Google e Presentazioni Google. Gmail utilizza la home page predefinita.
Le impostazioni del manifest di esempio consentono quanto segue:
- Trigger Calendario eventOpen e eventUpdated.
- (Solo Apps Script) Due soluzioni di conferenza di Calendar.
- Due azioni universali.
- Un Drive onItemsSelectedTrigger.
- Un'azione di composizione di Gmail e un trigger contestuale.
- Un oggetto linkPreviewTriggers di Documenti. Consulta Link di anteprima con smart chip.
- Un oggetto createActionTriggers di Documenti. Vedi Creare risorse di terze parti dal menu @.
- Interfacce specifiche per i file per Documenti, Fogli e Presentazioni.
- Un'opzione sidePanelUri e addOnOrigins di Google Meet.
- (Solo HTTP) Due HttpOptions per l'invio di un'intestazione di autorizzazione e il supporto del consenso granulare.
Il campo oauthScopes imposta gli ambiti di autorizzazione del progetto.
(Solo Apps Script) urlFetchWhitelist garantisce che gli endpoint recuperati corrispondano ai prefissi URL HTTPS specificati. Vedi Includere URL nella lista consentita.

I link negli esempi reindirizzano alle descrizioni dei campi nel riferimento del manifest per i componenti aggiuntivi di Apps Script e HTTP di Google Workspace.

I manifest includono altri componenti. I campi in addOns si riferiscono direttamente ai componenti aggiuntivi di Google Workspace. Questo esempio mostra solo una parte di un file manifest completo e non è funzionale da solo.

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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "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 consentiti

Utilizzi le liste consentite per designare URL specifici pre-approvati per l'accesso dal tuo script o componente aggiuntivo. Le liste consentite contribuiscono a proteggere i dati degli utenti. Quando definisci una lista consentita, i progetti di script non possono accedere agli URL che non sono stati aggiunti alla lista consentita.

Questo campo è facoltativo quando installi un deployment di test, ma è obbligatorio quando crei un deployment con controllo delle versioni.

Utilizzi le liste consentite quando lo script o il componente aggiuntivo esegue le seguenti azioni:

Recupera o recupera informazioni da una posizione esterna (ad esempio endpoint HTTPS) utilizzando il servizio UrlFetch di Apps Script. Per inserire gli URL nella lista consentita per il recupero, includi il campo urlFetchWhitelist nel file manifest.
Apre o visualizza un URL in risposta a un'azione dell'utente (obbligatorio per i componenti aggiuntivi di Google Workspace che aprono o visualizzano URL esterni a Google). Per inserire gli URL nella lista consentita per l'apertura, includi il campo addOns.common.openLinkUrlPrefixes nel file manifest.

Aggiungere prefissi alla lista consentita

Quando specifichi le liste consentite nel file manifest (includendo il campo addOns.common.openLinkUrlPrefixes o urlFetchWhitelist), devi includere un elenco di prefissi URL. I prefissi che aggiungi al manifest devono soddisfare i seguenti requisiti:

Ogni prefisso deve essere un URL valido.
Ogni prefisso deve utilizzare https://, non http://.
Ogni prefisso deve avere un dominio completo.
Ogni prefisso deve avere un percorso non vuoto. Ad esempio, https://www.google.com/ è valido, ma https://www.google.com no.
Puoi utilizzare i caratteri jolly per trovare una corrispondenza con i prefissi dei sottodomini degli URL.
È possibile utilizzare un singolo carattere jolly * nel campo addOns.common.openLinkUrlPrefixes per trovare tutti i link, ma questa operazione non è consigliata in quanto può esporre i dati di un utente a rischi e può prolungare la procedura di revisione dei componenti aggiuntivi. Utilizza un carattere jolly solo se la funzionalità del componente aggiuntivo lo richiede.

Quando viene determinato se un URL corrisponde a un prefisso nella lista consentita, si applicano le seguenti regole:

La corrispondenza del percorso è sensibile alle maiuscole.
Se il prefisso è identico all'URL, si tratta di una corrispondenza.
Se l'URL è uguale o un elemento secondario del prefisso, si verifica una corrispondenza.

Ad esempio, il prefisso https://example.com/foo corrisponde ai seguenti URL:

https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar

Utilizzo dei caratteri jolly

Puoi utilizzare un singolo carattere jolly (*) per trovare la corrispondenza con un sottodominio per i campi urlFetchWhitelist e addOns.common.openLinkUrlPrefixes. Non puoi utilizzare più di un carattere jolly per trovare corrispondenze con più sottodomini e il carattere jolly deve rappresentare il prefisso iniziale dell'URL.

Ad esempio, il prefisso https://*.example.com/foo corrisponde ai seguenti URL:

https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo

Il prefisso https://*.example.com/foo non corrisponde ai seguenti URL:

https://subdomain.example.com/bar (suffisso non corrispondente)
https://example.com/foo (deve essere presente almeno un sottodominio)

Alcune regole relative ai prefissi vengono applicate quando tenti di salvare il file manifest. Ad esempio, i seguenti prefissi causano un errore se sono presenti nel manifest quando tenti di salvare:

https://*.*.example.com/foo (sono vietati più caratteri jolly)
https://subdomain.*.example.com/foo (i caratteri jolly devono essere utilizzati come prefisso iniziale)