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 illustra i dettagli della configurazione di un manifest per un componente aggiuntivo di Google Workspace.

Struttura 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 del componente aggiuntivo.

Le proprietà manifest per i componenti aggiuntivi di Google Workspace sono organizzate nella sezione addOns della struttura dell'oggetto manifest.

• Per informazioni sui file manifest di Apps Script, consulta Struttura del manifest.

• Per informazioni sui file manifest per i componenti aggiuntivi creati con endpoint HTTP, consulta la risorsa projects.deployments.

Manifest per Google Chat

Anteprima per sviluppatori: disponibile nell'ambito del programma Anteprima per sviluppatori di Google Workspace, che concede l'accesso in anteprima a determinate funzionalità.

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

Le impostazioni di configurazione del manifest comuni (incluso addons.common) vengono ignorate in Chat. Anziché utilizzare il manifest del componente aggiuntivo, utilizza l'API Chat per configurare le seguenti impostazioni di Chat:

• Il nome, il logo e la descrizione dell'app Chat, che vengono visualizzati solo nell'interfaccia utente di Chat.
• Attivazione delle app di chat.

Se hai creato il componente aggiuntivo in Apps Script, devi anche aggiungere o aggiornare i seguenti oggetti nel file manifest:

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

Per la procedura di configurazione delle impostazioni di Chat per un plug-in, vedi Configurare un'app Google Chat.

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

I seguenti esempi di manifest mostrano la sezione di un file manifest che definisce un componente aggiuntivo di Google Workspace, inclusi i seguenti aspetti:

• La sezione addOns.common del manifest definisce il nome, l'URL del logo, i colori e altre impostazioni generali indipendenti dall'host per il componente aggiuntivo.

• Il file manifest definisce una home page comune, ma anche home page specifiche per Calendar, Drive, Documenti, Fogli e Presentazioni. Gmail utilizza la home page predefinita.

• Le impostazioni manifest di esempio abilitano quanto segue:

  • Trigger eventOpen e eventUpdated di Calendar.

  • (Solo Apps Script) Due soluzioni per conferenze di Calendar.

  • Due azioni universali.

  • Un account Drive onItemsSelectedTrigger.

  • Un'azione di composizione di Gmail e un attivatore contestuale.

  • Un oggetto linkPreviewTriggersdi Documenti. Per scoprire di più su questo attivatore, consulta Visualizza l'anteprima dei link con gli smart chip.

  • Un oggetto createActionTriggers di Documenti. Per scoprire di più su questo attivatore, consulta Creare risorse di terze parti dal menu @.

  • Interfacce specifiche per i file di Documenti, Fogli e Presentazioni.

  • (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 per il progetto (in genere obbligatori per i componenti aggiuntivi).

• (Solo Apps Script) Il campo urlFetchWhitelist garantisce che tutti gli endpoint recuperati corrispondano a un elenco specificato di prefissi URL HTTPS. Per ulteriori informazioni, consulta URL della lista consentita.

I link nei manifest di esempio rimandano alle descrizioni del campo nella documentazione di riferimento del manifest corrispondente per i componenti aggiuntivi Google Workspace Apps Script e HTTP.

Nota: i manifest includono altri componenti. I campi sotto il campo addOns si riferiscono direttamente ai componenti aggiuntivi di Google Workspace. Questo esempio è solo una parte di un file manifest completo e non è un manifest completamente funzionale.

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 nella lista consentita

Le liste consentite ti consentono di designare URL specifici preapprovati per l'accesso da parte dello script o del componente aggiuntivo. Le liste consentite aiutano 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 prova, ma è obbligatorio quando crei un deployment con versione.

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 nella lista consentita gli URL da recuperare, includi il campo urlFetchWhitelist nel file manifest.
• Apre o mostra un URL in risposta a un'azione dell'utente (obbligatorio per i componenti aggiuntivi di Google Workspace che aprono o mostrano URL esterni a Google). Per inserire nella lista consentita gli URL da aprire, includi il campo addOns.common.openLinkUrlPrefixes nel file manifest.

Nota: Lista consentita, come utilizzato in urlFetchWhitelist, è un termine deprecato che è sinonimo di lista consentita e viene sostituito da quest'ultimo. Per ulteriori informazioni, consulta Scrivere documentazione inclusiva.

Aggiunta di 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 aggiunti 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 non lo è.
• Puoi utilizzare i caratteri jolly per trovare una corrispondenza con i prefissi dei sottodomini dell'URL.
• È possibile utilizzare un singolo carattere jolly * nel campo addOns.common.openLinkUrlPrefixes per trovare corrispondenze per tutti i link, ma questa operazione non è consigliata in quanto può mettere a rischio i dati di un utente e prolungare la procedura di revisione dei componenti aggiuntivi. Utilizza un carattere jolly solo se la funzionalità del componente aggiuntivo lo richiede.

Per determinare 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 tratta di 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 una corrispondenza con un sottodominio sia per i campi urlFetchWhitelist sia per addOns.common.openLinkUrlPrefixes. Non puoi utilizzare più di un carattere jolly per associare 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 (mancata corrispondenza del suffisso)
• https://example.com/foo (deve essere presente almeno un sottodominio)

Alcune regole del prefisso vengono applicate quando provi a salvare il manifest. Ad esempio, i seguenti prefissi causano un errore se sono presenti nel manifest quando provi a salvare:

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