Questa pagina spiega come creare un componente aggiuntivo di Google Workspace che consente agli utenti di Documenti, Fogli e Presentazioni Google di visualizzare l'anteprima dei link da un servizio di terze parti.
Un componente aggiuntivo di Google Workspace può rilevare i link del tuo servizio e chiedere agli utenti di visualizzarli in anteprima. Puoi configurare un componente aggiuntivo per visualizzare l'anteprima di più pattern URL, ad esempio link a richieste di assistenza, lead di vendita e profili dei dipendenti.
In che modo gli utenti hanno visualizzato l'anteprima dei link
Per visualizzare l'anteprima dei link, gli utenti interagiscono con smart chip e schede.
Quando gli utenti digitano o incollano un URL in un documento, Documenti Google chiede di sostituire il link con uno smart chip. Lo smart chip mostra un'icona e un breve titolo o una descrizione dei contenuti del link. Quando l'utente passa il mouse sopra il chip, viene visualizzata un'interfaccia della scheda che mostra in anteprima ulteriori informazioni sul file o sul link.
Il seguente video mostra in che modo un utente converte un link in uno smart chip e visualizza l'anteprima di una scheda:
In che modo gli utenti visualizzano l'anteprima dei link in Fogli e Presentazioni
Gli smart chip di terze parti non sono supportati per le anteprime dei link in Fogli e Presentazioni. Quando gli utenti digitano o incollano un URL in un foglio di lavoro o in una presentazione, Fogli o Presentazioni chiede di sostituire il link con il titolo come testo collegato anziché come chip. Quando l'utente passa il mouse sopra il titolo del link, viene visualizzata un'interfaccia a scheda che mostra un'anteprima delle informazioni sul link.
L'immagine seguente mostra come viene visualizzato l'anteprima di un link in Fogli e Presentazioni:
Prerequisiti
Apps Script
- Un account Google Workspace.
- Un componente aggiuntivo di Google Workspace. Per creare un componente aggiuntivo, segui questa quickstart.
Node.js
- Un account Google Workspace.
- Un componente aggiuntivo di Google Workspace. Per creare un componente aggiuntivo, segui questa quickstart.
Python
- Un account Google Workspace.
- Un componente aggiuntivo di Google Workspace. Per creare un componente aggiuntivo, segui questa quickstart.
Java
- Un account Google Workspace.
- Un componente aggiuntivo di Google Workspace. Per creare un componente aggiuntivo, segui questa quickstart.
(Facoltativo) Configurare l'autenticazione su un servizio di terze parti
Se il componente aggiuntivo si connette a un servizio che richiede l'autorizzazione, gli utenti devono eseguire l'autenticazione al servizio per visualizzare l'anteprima dei link. Ciò significa che quando gli utenti incollano un link dal tuo servizio in un file di Documenti, Fogli o Presentazioni per la prima volta, il componente aggiuntivo deve richiamare il flusso di autorizzazione.
Per configurare un servizio OAuth o una richiesta di autorizzazione personalizzata, consulta una delle seguenti guide:
Se hai creato il componente aggiuntivo utilizzando Apps Script, consulta Connessione a servizi non Google da un componente aggiuntivo di Google Workspace.
Se hai creato il componente aggiuntivo utilizzando un runtime diverso, consulta Collegare il componente aggiuntivo a un servizio di terze parti.
Configurare le anteprime dei link per il componente aggiuntivo
Questa sezione spiega come configurare le anteprime dei link per il componente aggiuntivo, che include i seguenti passaggi:
- Configura le anteprime dei link nella risorsa di deployment o nel file manifest del componente aggiuntivo.
- Crea l'interfaccia di smart chip e schede per i tuoi link.
Configura le anteprime dei link
Per configurare le anteprime dei link, specifica le sezioni e i campi seguenti nella risorsa di deployment o nel file manifest del componente aggiuntivo:
- Nella sezione
addOns
, aggiungi il campodocs
per estendere Documenti, il camposheets
per estendere Fogli e il camposlides
per estendere Presentazioni. In ogni campo, implementa l'attivatore
linkPreviewTriggers
che include unrunFunction
(puoi definire questa funzione nella sezione seguente, Creare lo smart chip e la scheda).Per scoprire quali campi puoi specificare nel trigger
linkPreviewTriggers
, consulta la documentazione di riferimento per i file manifest di Apps Script o le risorse di deployment per altri runtime.Nel campo
oauthScopes
, aggiungi l'ambitohttps://www.googleapis.com/auth/workspace.linkpreview
in modo che gli utenti possano autorizzare il componente aggiuntivo a visualizzare l'anteprima dei link per loro conto.
Ad esempio, consulta la sezione oauthScopes
e addons
della seguente risorsa di deployment che configura le anteprime dei link per un servizio di richiesta di assistenza.
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://www.example.com/images/company-logo.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
},
"sheets": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
},
"slides": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
}
}
}
Nell'esempio, il componente aggiuntivo di Google Workspace mostra in anteprima i link per il servizio di richieste di assistenza di un'azienda. Il componente aggiuntivo specifica tre pattern
URL per visualizzare l'anteprima dei link. Ogni volta che un link corrisponde a uno dei pattern URL, la funzione di callback caseLinkPreview
crea e visualizza una scheda e uno smart chip oppure, in Fogli e Presentazioni, sostituisce l'URL con il titolo del link.
Creare lo smart chip e la scheda
Per restituire uno smart chip e una scheda per un link, devi implementare qualsiasi funzione specificata nell'oggetto linkPreviewTriggers
.
Quando un utente interagisce con un link che corrisponde a un pattern URL specificato, l'attivatore linkPreviewTriggers
si attiva e la sua funzione di callback trasmette l'oggetto evento EDITOR_NAME.matchedUrl.url
come argomento. Puoi utilizzare il payload di questo oggetto evento per creare lo smart chip e la scheda per l'anteprima del link.
Ad esempio, se un utente visualizza l'anteprima del link https://www.example.com/cases/123456
in Documenti, viene restituito il seguente payload di evento:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Per creare l'interfaccia della scheda, puoi utilizzare i widget per visualizzare le informazioni sul link. Puoi anche creare azioni che consentano agli utenti di aprire il link o modificarne i contenuti. Per un elenco dei widget e delle azioni disponibili, vedi Componenti supportati per le schede di anteprima.
Per creare lo smart chip e la scheda per l'anteprima link:
- Implementa la funzione specificata nella sezione
linkPreviewTriggers
della risorsa di deployment o del file manifest del componente aggiuntivo:- La funzione deve accettare un oggetto evento contenente
EDITOR_NAME.matchedUrl.url
come argomento e restituire un singolo oggettoCard
. - Se il servizio richiede l'autorizzazione, la funzione deve anche chiamare il flusso di autorizzazione.
- La funzione deve accettare un oggetto evento contenente
- Per ogni scheda di anteprima, implementa tutte le funzioni di callback che forniscono interattività dei widget per l'interfaccia. Ad esempio, se includi un pulsante "Visualizza link", puoi creare un'azione che specifichi una funzione di callback per aprire il link in una nuova finestra. Per scoprire di più sulle interazioni con i widget, consulta Azioni aggiuntive.
Il seguente codice crea la funzione di callback caseLinkPreview
per Documenti:
Apps Script
Node.js
Python
Java
Componenti supportati per le schede di anteprima
I componenti aggiuntivi di Google Workspace supportano i seguenti widget e azioni per le schede di anteprima dei link:
Apps Script
Campo Card Service (Servizio carta) | Tipo |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
IconImage |
Widget |
ButtonSet |
Widget |
TextButton |
Widget |
ImageButton |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Azione |
Navigation |
Azione È supportato soltanto il metodo updateCard . |
JSON
Campo scheda (google.apps.card.v1 ) |
Tipo |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
Icon |
Widget |
ButtonList |
Widget |
Button |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Azione |
Navigation |
Azione È supportato soltanto il metodo updateCard . |
Esempio completo: componente aggiuntivo della richiesta di assistenza
L'esempio seguente include un componente aggiuntivo di Google Workspace che mostra in anteprima i link alle richieste di assistenza di un'azienda in Documenti Google.
Nell'esempio:
- Visualizza in anteprima i link alle richieste di assistenza, come
https://www.example.com/support/cases/1234
. Lo smart chip mostra un'icona di assistenza, mentre la scheda di anteprima include l'ID richiesta e una descrizione. - Se la lingua dell'utente è impostata sullo spagnolo, lo smart chip localizza il suo
labelText
in spagnolo.
Risorsa di deployment
Apps Script
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
}
]
}
}
}
Codice
Apps Script
Node.js
Python
Java
Risorse correlate
- Visualizzare l'anteprima dei link di Google Libri con smart chip
- Testare il componente aggiuntivo
- Risorsa per l'implementazione di Documenti Google
- Interfacce delle schede per le anteprime dei link