Auf dieser Seite wird erläutert, wie Sie ein Google Workspace-Add-on erstellen, mit dem Google Docs-Nutzer Links von Drittanbietern ansehen können.
Ein Google Workspace-Add-on kann die Links Ihres Dienstes erkennen und Google Docs-Nutzer auffordern, sich eine Vorschau davon anzusehen. Sie können ein Add-on so konfigurieren, dass eine Vorschau mehrerer URL-Muster erstellt wird, z. B. Links zu Supportanfragen, Leads und Mitarbeiterprofile.
Vorschau von Links für Nutzer
Wenn Nutzer eine Vorschau von Links in einem Google Docs-Dokument ansehen möchten, interagieren Nutzer mit Smartchips und Karten:
Wenn Nutzer eine URL eingeben oder in ein Dokument einfügen, werden sie in Google Docs aufgefordert, den Link durch einen Smartchip zu ersetzen. Der Smartchip zeigt ein Symbol und einen kurzen Titel oder eine kurze Beschreibung des Linkinhalts an. Wenn der Nutzer den Mauszeiger auf den Chip bewegt, wird eine Kartenoberfläche mit weiteren Informationen zur Datei oder zum Link angezeigt.
Im folgenden Video sehen Sie, wie ein Nutzer einen Link in einen Smartchip umwandelt und eine Karte als Vorschau ansieht:
Voraussetzungen
Apps Script
- Ein Google Workspace-Konto
- Ein Google Workspace-Add-on. Folgen Sie dieser Kurzanleitung, um ein Add-on zu erstellen.
Node.js
- Ein Google Workspace-Konto
- Ein Google Workspace-Add-on. Folgen Sie dieser Kurzanleitung, um ein Add-on zu erstellen.
Python
- Ein Google Workspace-Konto
- Ein Google Workspace-Add-on. Folgen Sie dieser Kurzanleitung, um ein Add-on zu erstellen.
Java
- Ein Google Workspace-Konto
- Ein Google Workspace-Add-on. Folgen Sie dieser Kurzanleitung, um ein Add-on zu erstellen.
Optional: Authentifizierung bei einem Drittanbieterdienst einrichten
Wenn das Add-on eine Verbindung zu einem Dienst herstellt, für den eine Autorisierung erforderlich ist, müssen sich die Nutzer beim Dienst authentifizieren, um eine Vorschau der Links aufrufen zu können. Wenn also Nutzer ihren Link zum ersten Mal in ein Google Docs-Dokument einfügen, müssen sie mit dem Add-on aufgerufen werden.
Informationen zum Einrichten eines OAuth-Dienstes oder einer benutzerdefinierten Autorisierungsaufforderung finden Sie in einer der folgenden Anleitungen:
Wenn Sie Ihr Add-on mit Apps Script erstellt haben, finden Sie weitere Informationen unter Verbindung zu einem Google-Dienst über ein Google Workspace-Add-on herstellen.
Wenn Sie das Add-on mit einer anderen Laufzeit erstellt haben, finden Sie weitere Informationen unter Add-on mit einem Drittanbieterdienst verbinden.
Linkvorschau für das Add-on einrichten
In diesem Abschnitt wird beschrieben, wie Sie die Linkvorschau für Ihr Add-on einrichten. Gehen Sie dazu so vor:
- Konfigurieren Sie Linkvorschauen in der Deployment-Ressource oder Manifestdatei Ihres Add-ons.
- Erstellen Sie den Smartchip und die Kartenschnittstelle für Ihre Links.
Linkvorschau konfigurieren
Geben Sie die folgenden Abschnitte und Felder in der Bereitstellungsressource oder in der Manifestdatei des Add-ons an, um Linkvorschauen zu konfigurieren:
- Fügen Sie im Abschnitt
addOns
das Felddocs
hinzu, um Google Docs zu erweitern. Implementieren Sie im Feld
docs
denlinkPreviewTriggers
-Trigger, der einenrunFunction
enthält. Sie definieren diese Funktion im folgenden Abschnitt Smartchip und Karte erstellen.Informationen zu den Feldern, die Sie im
linkPreviewTriggers
-Trigger angeben können, finden Sie in der Referenzdokumentation zu Apps Script-Manifestdateien oder unter Bereitstellungsressourcen für andere Laufzeiten.Fügen Sie im Feld
oauthScopes
den Bereichhttps://www.googleapis.com/auth/workspace.linkpreview
hinzu, damit Nutzer das Add-on für die Vorschau von Links in ihrem Namen autorisieren können.
Sehen Sie sich beispielsweise die Abschnitte oauthScopes
und addons
einer Bereitstellungsressource an, die die Linkvorschauen für einen Supportfalldienst konfigurieren:
{
"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"
}
}
]
}
}
}
Im Beispiel wird im Google Workspace-Add-on eine Vorschau der Links für den Supportfall eines Unternehmens angezeigt. Das Add-on gibt drei URL-Muster für die Vorschau von Links an. Wenn ein Link mit einem der URL-Muster in einem Google Docs-Dokument übereinstimmt, erstellt die Callback-Funktion caseLinkPreview
einen Smartchip und eine Karte.
Smartchip und Karte erstellen
Damit ein Smartchip und eine Smartcard für einen Link zurückgegeben werden, müssen Sie alle Funktionen implementieren, die Sie im Objekt linkPreviewTriggers
angegeben haben.
Wenn ein Nutzer mit einem Link interagiert, der mit einem bestimmten URL-Muster übereinstimmt, wird der Trigger linkPreviewTriggers
ausgelöst und die Callback-Funktion übergibt das Ereignisobjekt docs.matchedUrl.url
als Argument. Sie verwenden die Nutzlast dieses Ereignisobjekts, um den Smartchip und die Karte für die Linkvorschau zu erstellen.
Für ein Add-on, das beispielsweise das URL-Muster example.com/cases
angibt, wird die folgende Ereignisnutzlast zurückgegeben, wenn ein Nutzer eine Vorschau des Links https://www.example.com/cases/123456
aufruft:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Zum Erstellen der Kartenschnittstelle verwenden Sie Widgets, um Informationen zum Link anzuzeigen. Sie können auch Aktionen erstellen, mit denen Nutzer den Link öffnen oder seinen Inhalt ändern können. Eine Liste der verfügbaren Widgets und Aktionen finden Sie unter Unterstützte Komponenten für Vorschaukarten.
So erstellen Sie den Smartchip und die Karte für eine Linkvorschau:
- Implementieren Sie die Funktion, die Sie im Abschnitt
linkPreviewTriggers
der Deployment-Ressource oder Manifestdatei des Add-ons angegeben haben:- Die Funktion muss ein Ereignisobjekt, das
docs.matchedUrl.url
enthält, als Argument akzeptieren und ein einzelnesCard
-Objekt zurückgeben. - Wenn für Ihren Dienst eine Autorisierung erforderlich ist, muss die Funktion auch den Autorisierungsvorgang aufrufen.
- Die Funktion muss ein Ereignisobjekt, das
- Implementieren Sie für jede Vorschaukarte die Callback-Funktionen, die zur Interaktion mit dem Widget verwendet werden. Wenn Sie beispielsweise eine Schaltfläche in die Benutzeroberfläche einfügen, sollte diese eine angehängte
Action
und eine implementierte Callback-Funktion haben, die beim Klicken auf die Schaltfläche ausgeführt wird.
Mit dem folgenden Code wird die Callback-Funktion caseLinkPreview
erstellt:
Apps Script
Node.js
Python
Java
Unterstützte Komponenten für Vorschaukarten
Google Workspace-Add-ons unterstützen die folgenden Widgets und Aktionen für Karten mit Linkvorschau:
Apps Script
Feld „Kartendienst“ | Typ |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
IconImage |
Widget |
ButtonSet |
Widget |
TextButton |
Widget |
ImageButton |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Aktion |
Navigation |
Aktion Nur die Methode updateCard wird unterstützt. |
JSON
Feld „Karte“ (google.apps.card.v1 ) |
Typ |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
Icon |
Widget |
ButtonList |
Widget |
Button |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Aktion |
Navigation |
Aktion Nur die Methode updateCard wird unterstützt. |
Vollständiges Beispiel: Add-on für Supportanfragen
Im folgenden Beispiel sehen Sie ein Google Workspace-Add-on, mit dem Links zu Supportfällen und Mitarbeiterprofilen eines Unternehmens angezeigt werden.
Das Beispiel führt Folgendes aus:
- Vorschauen enthalten Links zu Supportanfragen, z. B.
https://www.example.com/support/cases/1234
. Der Smartchip zeigt ein Supportsymbol an. Die Vorschaukarte enthält die Fall-ID und eine Beschreibung. - Vorschau von Links zu Supportfall-Agents wie
https://www.example.com/people/rosario-cruz
anzeigen. Auf dem Smartchip ist ein Personensymbol zu sehen und auf der Vorschaukarte sind Name, E-Mail-Adresse, Stellenbezeichnung und Profilbild des Mitarbeiters zu sehen. - Wenn die Sprache des Nutzers auf Spanisch festgelegt ist, lokalisiert der Smartchip
labelText
in Spanisch.
Deployment-Ressource
Apps Script
{
"timeZone": "America/New_York",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.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",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "peopleLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-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"
},
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}