Na tej stronie znajdziesz instrukcje tworzenia dodatku Google Workspace, który umożliwia użytkownikom Dokumentów, Arkuszy i Prezentacji Google wyświetlanie podglądu linków z usługi innej firmy.
Dodatek Google Workspace może wykrywać linki do Twojej usługi i wyświetlać użytkownikom prośbę o ich wyświetlenie. Możesz skonfigurować dodatek, aby wyświetlać podgląd wielu wzorców adresów URL, takich jak linki do zgłoszeń pomocy, kontaktów do potencjalnych klientów i profili pracowników.
Jak użytkownicy wyświetlają podgląd linków
Aby wyświetlić podgląd linków, użytkownicy muszą wchodzić w interakcję z elementami inteligentnymi i kartami.
Gdy użytkownicy wpisują lub wklejają adres URL w dokumencie lub arkuszu kalkulacyjnym, Dokumenty lub Arkusze Google wyświetlają prompt z prośbą o zastąpienie linku elementem inteligentnym. Element inteligentny wyświetla ikonę oraz krótki tytuł lub opis treści linku. Gdy użytkownik najedzie na element, zobaczy interfejs karty z podglądem dodatkowych informacji o pliku lub linku.
Ten film pokazuje, jak użytkownik przekonwertowuje link na element inteligentny i wyświetla podgląd karty:
Jak użytkownicy wyświetlają podgląd linków w Prezentacjach
Elementy inteligentne innych firm nie są obsługiwane w przypadku podglądu linków w Prezentacjach. Gdy użytkownicy wpisują lub wklejają adres URL w prezentacji, Slides wyświetla prompt z prośbą o zastąpienie linku jego tytułem jako tekstem linkowanym zamiast elementem. Gdy użytkownik najedzie kursorem na tytuł linku, zobaczy interfejs karty z podglądem informacji o linku.
Na poniższym obrazku widać, jak link jest wyświetlany w Prezentacjach Google:
Wymagania wstępne
Google Apps Script
- Konto Google Workspace.
- dodatkiem do Google Workspace; Aby utworzyć dodatek, skorzystaj z krótkiego wprowadzenia.
Node.js
- Konto Google Workspace.
- dodatkiem do Google Workspace; Aby utworzyć dodatek, skorzystaj z krótkiego przewodnika.
Python
- Konto Google Workspace.
- dodatkiem do Google Workspace; Aby utworzyć dodatek, skorzystaj z krótkiego wprowadzenia.
Java
- Konto Google Workspace.
- dodatkiem do Google Workspace; Aby utworzyć dodatek, skorzystaj z krótkiego przewodnika.
Opcjonalnie: skonfiguruj uwierzytelnianie w usłudze zewnętrznej
Jeśli dodatek łączy się z usługą, która wymaga autoryzacji, użytkownicy muszą się zalogować w tej usłudze, aby wyświetlić podgląd linków. Oznacza to, że gdy użytkownicy wklejają link z Twojej usługi do pliku Dokumentów, Arkuszy lub Prezentacji po raz pierwszy, Twój dodatek musi wywołać proces autoryzacji.
Aby skonfigurować usługę OAuth lub niestandardowy monit autoryzacji, przeczytaj artykuł Łączenie dodatku z usługą innej firmy.
Konfigurowanie podglądów linków dla dodatku
Z tej sekcji dowiesz się, jak skonfigurować podgląd linków dla swojego dodatku. Obejmuje ona te kroki:
- Skonfiguruj podglądy linków w pliku manifestu dodatku.
- Utwórz interfejs elementu inteligentnego i karty dla swoich linków.
Konfigurowanie podglądów linków
Aby skonfigurować podgląd linku, w pliku manifestu dodatku określ te sekcje i pola:
- W sekcji
addOns
dodaj poledocs
, aby rozszerzyć uprawnienia dostępu do Dokumentów, polesheets
, aby rozszerzyć uprawnienia dostępu do Arkuszy, oraz poleslides
, aby rozszerzyć uprawnienia dostępu do Prezentacji. W każdym polu zastosuj funkcję
linkPreviewTriggers
, która zawiera funkcjęrunFunction
(definicję tej funkcji znajdziesz w sekcji Tworzenie elementu inteligentnego i karty).Aby dowiedzieć się, które pola możesz określić w wyzwalaczu
linkPreviewTriggers
, zapoznaj się z dokumentacją referencyjną dotyczącą pliku manifestu Apps Script lub zasobów wdrożonych w przypadku innych środowisk wykonawczych.W polu
oauthScopes
dodaj zakreshttps://www.googleapis.com/auth/workspace.linkpreview
, aby użytkownicy mogli zezwolić dodatkowi na wyświetlanie podglądu linków w ich imieniu.
Przykładowo zobacz sekcje oauthScopes
i addons
w tym pliku manifestu, który konfiguruje podglądy linków dla usługi zgłoszeń do zespołu pomocy.
{
"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"
}
}
]
}
}
}
W tym przykładzie podgląd dodatku Google Workspace zawiera linki do zgłoszeń do pomocy technicznej firmy. Wtyczka określa 3 wzorce adresów URL, które mają być wyświetlane w podglądzie. Gdy link pasuje do jednego ze wzorów adresów URL, funkcja wywołania caseLinkPreview
tworzy i wyświetla kartę oraz element inteligentny w Dokumentach, Arkuszach lub Prezentacjach i zastępuje adres URL tytułem linku.
Tworzenie elementu inteligentnego i karty
Aby zwrócić element inteligentny i kartę dla linku, musisz zaimplementować wszystkie funkcje określone w obiekcie linkPreviewTriggers
.
Gdy użytkownik kliknie link pasujący do określonego wzorca adresu URL, zostanie wywołany element wyzwalający linkPreviewTriggers
, a jego funkcja wywołania zwróci obiekt zdarzenia EDITOR_NAME.matchedUrl.url
jako argument. Za pomocą ładunku tego obiektu zdarzenia możesz tworzyć inteligentne elementy i karty do podglądu linku.
Jeśli np. użytkownik wyświetli podgląd linku https://www.example.com/cases/123456
w Dokumentach, zwrócony zostanie ten ładunek zdarzenia:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Aby utworzyć interfejs karty, użyj widżetów do wyświetlania informacji o linku. Możesz też tworzyć działania, które umożliwiają użytkownikom otwieranie linku lub modyfikowanie jego zawartości. Listę dostępnych widżetów i działań znajdziesz w artykule Obsługiwane komponenty kart podglądu.
Aby utworzyć element inteligentny i kartę podglądu linku:
- Wdroż funkcję określoną w sekcji
linkPreviewTriggers
w pliku manifestu dodatku:- Funkcja musi przyjmować jako argument obiekt zdarzenia zawierający
EDITOR_NAME.matchedUrl.url
i zwracać pojedynczy obiektCard
. - Jeśli usługa wymaga autoryzacji, funkcja musi też wywoływać przepływ autoryzacji.
- Funkcja musi przyjmować jako argument obiekt zdarzenia zawierający
- W przypadku każdej karty podglądu zaimplementuj funkcje wywołania zwrotnego, które zapewniają interaktywność widżetu w interfejsie. Jeśli na przykład dodasz przycisk „Wyświetl link”, możesz utworzyć działanie, które określa funkcję wywołania zwrotnego służącą do otwierania linku w nowym oknie. Więcej informacji o interakcjach z widżetami znajdziesz w sekcji Działania dotyczące dodatków.
Poniższy kod tworzy funkcję wywołania zwrotnego caseLinkPreview
dla Docs:
Google Apps Script
Node.js
Python
Java
Obsługiwane komponenty do tworzenia kart podglądu
Dodatki Google Workspace obsługują te widżety i działania dotyczące kart z podglądem linków:
Google Apps Script
Pole Usługa karty | Typ |
---|---|
TextParagraph |
Widżet |
DecoratedText |
Widżet |
Image |
Widżet |
IconImage |
Widżet |
ButtonSet |
Widżet |
TextButton |
Widżet |
ImageButton |
Widżet |
Grid |
Widżet |
Divider |
Widżet |
OpenLink |
Działanie |
Navigation |
Działanie Obsługiwana jest tylko metoda updateCard . |
JSON
Pole Karta (google.apps.card.v1 ) |
Typ |
---|---|
TextParagraph |
Widżet |
DecoratedText |
Widżet |
Image |
Widżet |
Icon |
Widżet |
ButtonList |
Widżet |
Button |
Widżet |
Grid |
Widżet |
Divider |
Widżet |
OpenLink |
Działanie |
Navigation |
Działanie Obsługiwana jest tylko metoda updateCard . |
Pełny przykład: dodatek do zgłoszenia do zespołu pomocy
W tym przykładzie pokazano dodatek Google Workspace, który wyświetla podgląd linków do zgłoszeń do zespołu pomocy firmy w Dokumentach Google.
Przykład wykonuje te czynności:
- wyświetla podgląd linków do zgłoszeń do zespołu pomocy, takich jak
https://www.example.com/support/cases/1234
. Element inteligentny wyświetla ikonę pomocy, a karta podglądu zawiera identyfikator zgłoszenia i opis. - Jeśli język użytkownika to hiszpański, inteligentny element lokalizuje
labelText
na hiszpański.
Plik manifestu
Google 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"
}
]
}
}
}
Kod
Google Apps Script
Node.js
Python
Java
Przydatne materiały
- Linki do podglądu w Książkach Google z elementami inteligentnymi
- Testowanie dodatku
- plik manifestu Dokumentów Google
- Interfejsy kart podglądu linków