Prévisualiser les liens avec les chips intelligents

Cette page explique comment créer un module complémentaire Google Workspace permettant aux utilisateurs de Google Docs, Sheets et Slides de prévisualiser les liens d'un service tiers.

Un module complémentaire Google Workspace peut détecter les liens de votre service et inviter les utilisateurs à les prévisualiser. Vous pouvez configurer un module complémentaire pour prévisualiser plusieurs formats d'URL, tels que des liens vers des demandes d'assistance, des prospects commerciaux et des profils d'employés.

Comment les utilisateurs prévisualisent-ils les liens ?

Pour prévisualiser des liens, les utilisateurs interagissent avec des chips intelligents et des fiches.

L'utilisateur affiche un aperçu d'une carte.

Lorsque les utilisateurs saisissent ou collent une URL dans un document, Google Docs les invite à remplacer le lien par un chip intelligent. Le chip intelligent affiche une icône et un titre ou une description court du contenu du lien. Lorsque l'utilisateur pointe sur le chip, il voit une interface de fiche qui affiche plus d'informations sur le fichier ou le lien.

La vidéo suivante montre comment un utilisateur convertit un lien en chip intelligent et affiche un aperçu d'une fiche:

Prévisualisation des liens dans Sheets et Slides par les utilisateurs

Les chips intelligents tiers ne sont pas compatibles avec les aperçus de liens dans Sheets et Slides. Lorsque les utilisateurs saisissent ou collent une URL dans une feuille de calcul ou une présentation, Sheets ou Slides les invite à remplacer le lien par son titre en tant que texte lié plutôt que sous forme de chip. Lorsque l'utilisateur pointe sur le titre du lien, il voit une interface de fiche qui affiche un aperçu des informations sur le lien.

L'image suivante illustre le rendu d'un aperçu de lien dans Sheets et Slides:

Exemple d'aperçu de lien pour Sheets et Slides

Prérequis

Apps Script ;

  • Un compte Google Workspace
  • Un module complémentaire Google Workspace. Pour créer un module complémentaire, suivez ce quickstart.

Node.js

  • Un compte Google Workspace
  • Un module complémentaire Google Workspace. Pour créer un module complémentaire, suivez ce quickstart.

Python

  • Un compte Google Workspace
  • Un module complémentaire Google Workspace. Pour créer un module complémentaire, suivez ce quickstart.

Java

  • Un compte Google Workspace
  • Un module complémentaire Google Workspace. Pour créer un module complémentaire, suivez ce quickstart.

Facultatif: Configurer l'authentification auprès d'un service tiers

Si votre module complémentaire se connecte à un service nécessitant une autorisation, les utilisateurs doivent s'authentifier auprès du service pour prévisualiser les liens. Cela signifie que lorsque les utilisateurs collent un lien de votre service dans un fichier Docs, Sheets ou Slides pour la première fois, votre module complémentaire doit appeler le flux d'autorisation.

Pour configurer un service OAuth ou une invite d'autorisation personnalisée, consultez l'un des guides suivants:

Cette section explique comment configurer les aperçus des liens pour votre module complémentaire, en procédant comme suit:

  1. Configurez les aperçus de liens dans la ressource de déploiement ou le fichier manifeste de votre module complémentaire.
  2. Créez l'interface de carte à puce intelligente pour vos liens.

Configurer les aperçus de lien

Pour configurer les aperçus de liens, spécifiez les sections et les champs suivants dans la ressource de déploiement ou le fichier manifeste de votre module complémentaire:

  1. Dans la section addOns, ajoutez le champ docs pour étendre Docs, le champ sheets pour étendre Sheets et le champ slides pour étendre Slides.
  2. Dans chaque champ, implémentez le déclencheur linkPreviewTriggers qui inclut un runFunction (vous définissez cette fonction dans la section suivante, Créer le chip intelligent et la carte).

    Pour savoir quels champs vous pouvez spécifier dans le déclencheur linkPreviewTriggers, consultez la documentation de référence sur les fichiers manifestes Apps Script ou les ressources de déploiement pour d'autres environnements d'exécution.

  3. Dans le champ oauthScopes, ajoutez le champ d'application https://www.googleapis.com/auth/workspace.linkpreview afin que les utilisateurs puissent autoriser le module complémentaire à prévisualiser les liens en leur nom.

Par exemple, consultez la section oauthScopes et addons de la ressource de déploiement suivante, qui configure les aperçus de lien pour un service de demande d'assistance.

{
  "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"
          }
        }
      ]
    }
  }
}

Dans cet exemple, le module complémentaire Google Workspace affiche un aperçu des liens vers le service de demande d'assistance d'une entreprise. Celui-ci spécifie trois formats d'URL pour prévisualiser les liens. Chaque fois qu'un lien correspond à l'un des formats d'URL, la fonction de rappel caseLinkPreview crée et affiche une fiche et un chip intelligent, ou bien dans Sheets et Slides, elle remplace l'URL par le titre du lien.

Créer une puce et une carte intelligentes

Pour renvoyer une puce ou une carte à puce pour un lien, vous devez implémenter toutes les fonctions que vous avez spécifiées dans l'objet linkPreviewTriggers.

Lorsqu'un utilisateur interagit avec un lien correspondant à un format d'URL spécifié, le déclencheur linkPreviewTriggers s'active et sa fonction de rappel transmet l'objet d'événement EDITOR_NAME.matchedUrl.url en tant qu'argument. Vous utiliserez la charge utile de cet objet d'événement pour créer le chip intelligent et la carte pour l'aperçu de votre lien.

Par exemple, si un utilisateur prévisualise le lien https://www.example.com/cases/123456 dans Docs, la charge utile d'événement suivante est renvoyée:

JSON

{
  "docs": {
    "matchedUrl": {
        "url": "https://www.example.com/support/cases/123456"
    }
  }
}

Pour créer l'interface de la fiche, vous utilisez des widgets pour afficher des informations sur le lien. Vous pouvez également créer des actions qui permettent aux utilisateurs d'ouvrir le lien ou de modifier son contenu. Pour obtenir la liste des widgets et actions disponibles, consultez la section Composants compatibles pour les fiches d'aperçu.

Pour créer une icône et une carte intelligentes pour l'aperçu d'un lien, procédez comme suit:

  1. Implémentez la fonction que vous avez spécifiée dans la section linkPreviewTriggers de la ressource de déploiement de votre module complémentaire ou du fichier manifeste :
    1. La fonction doit accepter un objet d'événement contenant EDITOR_NAME.matchedUrl.url comme argument et renvoyer un seul objet Card.
    2. Si votre service nécessite une autorisation, la fonction doit également appeler le flux d'autorisation.
  2. Pour chaque fiche d'aperçu, implémentez des fonctions de rappel qui fournissent une interactivité des widgets pour l'interface. Par exemple, si vous incluez un bouton "Afficher le lien", vous pouvez créer une action qui spécifie une fonction de rappel pour ouvrir le lien dans une nouvelle fenêtre. Pour en savoir plus sur les interactions avec les widgets, consultez Actions des modules complémentaires.

Le code suivant crée la fonction de rappel caseLinkPreview pour Docs:

Apps Script ;

apps-script/3p-resources/3p-resources.gs
/**
* Entry point for a support case link preview.
*
* @param {!Object} event The event object.
* @return {!Card} The resulting preview link card.
*/
function caseLinkPreview(event) {

  // If the event object URL matches a specified pattern for support case links.
  if (event.docs.matchedUrl.url) {

    // Uses the event object to parse the URL and identify the case details.
    const caseDetails = parseQuery(event.docs.matchedUrl.url);

    // Builds a preview card with the case name, and description
    const caseHeader = CardService.newCardHeader()
      .setTitle(`Case ${caseDetails["name"][0]}`);
    const caseDescription = CardService.newTextParagraph()
      .setText(caseDetails["description"][0]);

    // Returns the card.
    // Uses the text from the card's header for the title of the smart chip.
    return CardService.newCardBuilder()
      .setHeader(caseHeader)
      .addSection(CardService.newCardSection().addWidget(caseDescription))
      .build();
  }
}

/**
* Extracts the URL parameters from the given URL.
*
* @param {!string} url The URL to parse.
* @return {!Map} A map with the extracted URL parameters.
*/
function parseQuery(url) {
  const query = url.split("?")[1];
  if (query) {
    return query.split("&")
    .reduce(function(o, e) {
      var temp = e.split("=");
      var key = temp[0].trim();
      var value = temp[1].trim();
      value = isNaN(value) ? value : Number(value);
      if (o[key]) {
        o[key].push(value);
      } else {
        o[key] = [value];
      }
      return o;
    }, {});
  }
  return null;
}

Node.js

node/3p-resources/index.js
/**
 * 
 * A support case link preview.
 *
 * @param {!URL} url The event object.
 * @return {!Card} The resulting preview link card.
 */
function caseLinkPreview(url) {
  // Builds a preview card with the case name, and description
  // Uses the text from the card's header for the title of the smart chip.
  // Parses the URL and identify the case details.
  const name = `Case ${url.searchParams.get("name")}`;
  return {
    action: {
      linkPreview: {
        title: name,
        previewCard: {
          header: {
            title: name
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: url.searchParams.get("description")
              }
            }]
          }]
        }
      }
    }
  };
}

Python

python/3p-resources/create_link_preview/main.py

def case_link_preview(url):
    """A support case link preview.
    Args:
      url: A matching URL.
    Returns:
      The resulting preview link card.
    """

    # Parses the URL and identify the case details.
    query_string = parse_qs(url.query)
    name = f'Case {query_string["name"][0]}'
    # Uses the text from the card's header for the title of the smart chip.
    return {
        "action": {
            "linkPreview": {
                "title": name,
                "previewCard": {
                    "header": {
                        "title": name
                    },
                    "sections": [{
                        "widgets": [{
                            "textParagraph": {
                                "text": query_string["description"][0]
                            }
                        }]
                    }],
                }
            }
        }
    }

Java

java/3p-resources/src/main/java/CreateLinkPreview.java
/**
 * A support case link preview.
 *
 * @param url A matching URL.
 * @return The resulting preview link card.
 */
JsonObject caseLinkPreview(URL url) throws UnsupportedEncodingException {
  // Parses the URL and identify the case details.
  Map<String, String> caseDetails = new HashMap<String, String>();
  for (String pair : url.getQuery().split("&")) {
      caseDetails.put(URLDecoder.decode(pair.split("=")[0], "UTF-8"), URLDecoder.decode(pair.split("=")[1], "UTF-8"));
  }

  // Builds a preview card with the case name, and description
  // Uses the text from the card's header for the title of the smart chip.
  JsonObject cardHeader = new JsonObject();
  String caseName = String.format("Case %s", caseDetails.get("name"));
  cardHeader.add("title", new JsonPrimitive(caseName));

  JsonObject textParagraph = new JsonObject();
  textParagraph.add("text", new JsonPrimitive(caseDetails.get("description")));

  JsonObject widget = new JsonObject();
  widget.add("textParagraph", textParagraph);

  JsonArray widgets = new JsonArray();
  widgets.add(widget);

  JsonObject section = new JsonObject();
  section.add("widgets", widgets);

  JsonArray sections = new JsonArray();
  sections.add(section);

  JsonObject previewCard = new JsonObject();
  previewCard.add("header", cardHeader);
  previewCard.add("sections", sections);

  JsonObject linkPreview = new JsonObject();
  linkPreview.add("title", new JsonPrimitive(caseName));
  linkPreview.add("previewCard", previewCard);

  JsonObject action = new JsonObject();
  action.add("linkPreview", linkPreview);

  JsonObject renderActions = new JsonObject();
  renderActions.add("action", action);

  return renderActions;
}

Composants compatibles avec les fiches d'aperçu

Les modules complémentaires Google Workspace sont compatibles avec les actions et widgets suivants pour les fiches d'aperçu des liens:

Apps Script ;

Champ du service de carte Type
TextParagraph Widget
DecoratedText Widget
Image Widget
IconImage Widget
ButtonSet Widget
TextButton Widget
ImageButton Widget
Grid Widget
Divider Widget
OpenLink Action
Navigation Action
Seule la méthode updateCard est acceptée.

JSON

Champ de la carte (google.apps.card.v1) Type
TextParagraph Widget
DecoratedText Widget
Image Widget
Icon Widget
ButtonList Widget
Button Widget
Grid Widget
Divider Widget
OpenLink Action
Navigation Action
Seule la méthode updateCard est acceptée.

Exemple complet: Module complémentaire pour les demandes d'assistance

L'exemple suivant présente un module complémentaire Google Workspace qui affiche un aperçu des liens vers les demandes d'assistance d'une entreprise dans Google Docs.

en effectuant les opérations suivantes :

  • Aperçu des liens vers des demandes d'assistance, telles que https://www.example.com/support/cases/1234. Le chip intelligent affiche une icône d'assistance, et la fiche d'aperçu inclut le numéro de demande et une description.
  • Si les paramètres régionaux de l'utilisateur sont définis sur l'espagnol, le chip intelligent localise son labelText en espagnol.

Ressource de déploiement

Apps Script ;

apps-script/3p-resources/appsscript.json
{
  "timeZone": "America/New_York",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.linkpreview",
    "https://www.googleapis.com/auth/workspace.linkcreate"
  ],
  "addOns": {
    "common": {
      "name": "Manage support cases",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-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"
        }
      ],
      "createActionTriggers": [
        {
          "id": "createCase",
          "labelText": "Create support case",
          "localizedLabelText": {
            "es": "Crear caso de soporte"
          },
          "runFunction": "createCaseInputCard",
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-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/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"
        }
      ]
    }
  }
}

Coder

Apps Script ;

apps-script/3p-resources/3p-resources.gs
/**
* Entry point for a support case link preview.
*
* @param {!Object} event The event object.
* @return {!Card} The resulting preview link card.
*/
function caseLinkPreview(event) {

  // If the event object URL matches a specified pattern for support case links.
  if (event.docs.matchedUrl.url) {

    // Uses the event object to parse the URL and identify the case details.
    const caseDetails = parseQuery(event.docs.matchedUrl.url);

    // Builds a preview card with the case name, and description
    const caseHeader = CardService.newCardHeader()
      .setTitle(`Case ${caseDetails["name"][0]}`);
    const caseDescription = CardService.newTextParagraph()
      .setText(caseDetails["description"][0]);

    // Returns the card.
    // Uses the text from the card's header for the title of the smart chip.
    return CardService.newCardBuilder()
      .setHeader(caseHeader)
      .addSection(CardService.newCardSection().addWidget(caseDescription))
      .build();
  }
}

/**
* Extracts the URL parameters from the given URL.
*
* @param {!string} url The URL to parse.
* @return {!Map} A map with the extracted URL parameters.
*/
function parseQuery(url) {
  const query = url.split("?")[1];
  if (query) {
    return query.split("&")
    .reduce(function(o, e) {
      var temp = e.split("=");
      var key = temp[0].trim();
      var value = temp[1].trim();
      value = isNaN(value) ? value : Number(value);
      if (o[key]) {
        o[key].push(value);
      } else {
        o[key] = [value];
      }
      return o;
    }, {});
  }
  return null;
}

Node.js

node/3p-resources/index.js
/**
 * Responds to any HTTP request related to link previews.
 *
 * @param {Object} req An HTTP request context.
 * @param {Object} res An HTTP response context.
 */
exports.createLinkPreview = (req, res) => {
  const event = req.body;
  if (event.docs.matchedUrl.url) {
    const url = event.docs.matchedUrl.url;
    const parsedUrl = new URL(url);
    // If the event object URL matches a specified pattern for preview links.
    if (parsedUrl.hostname === 'example.com') {
      if (parsedUrl.pathname.startsWith('/support/cases/')) {
        return res.json(caseLinkPreview(parsedUrl));
      }
    }
  }
};


/**
 * 
 * A support case link preview.
 *
 * @param {!URL} url The event object.
 * @return {!Card} The resulting preview link card.
 */
function caseLinkPreview(url) {
  // Builds a preview card with the case name, and description
  // Uses the text from the card's header for the title of the smart chip.
  // Parses the URL and identify the case details.
  const name = `Case ${url.searchParams.get("name")}`;
  return {
    action: {
      linkPreview: {
        title: name,
        previewCard: {
          header: {
            title: name
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: url.searchParams.get("description")
              }
            }]
          }]
        }
      }
    }
  };
}

Python

python/3p-resources/create_link_preview/main.py
from typing import Any, Mapping
from urllib.parse import urlparse, parse_qs

import flask
import functions_framework


@functions_framework.http
def create_link_preview(req: flask.Request):
    """Responds to any HTTP request related to link previews.
    Args:
      req: An HTTP request context.
    Returns:
      An HTTP response context.
    """
    event = req.get_json(silent=True)
    if event["docs"]["matchedUrl"]["url"]:
        url = event["docs"]["matchedUrl"]["url"]
        parsed_url = urlparse(url)
        # If the event object URL matches a specified pattern for preview links.
        if parsed_url.hostname == "example.com":
            if parsed_url.path.startswith("/support/cases/"):
                return case_link_preview(parsed_url)

    return {}




def case_link_preview(url):
    """A support case link preview.
    Args:
      url: A matching URL.
    Returns:
      The resulting preview link card.
    """

    # Parses the URL and identify the case details.
    query_string = parse_qs(url.query)
    name = f'Case {query_string["name"][0]}'
    # Uses the text from the card's header for the title of the smart chip.
    return {
        "action": {
            "linkPreview": {
                "title": name,
                "previewCard": {
                    "header": {
                        "title": name
                    },
                    "sections": [{
                        "widgets": [{
                            "textParagraph": {
                                "text": query_string["description"][0]
                            }
                        }]
                    }],
                }
            }
        }
    }

Java

java/3p-resources/src/main/java/CreateLinkPreview.java
import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import com.google.gson.JsonPrimitive;

import java.io.UnsupportedEncodingException;
import java.net.URL;
import java.net.URLDecoder;
import java.util.HashMap;
import java.util.Map;

public class CreateLinkPreview implements HttpFunction {
  private static final Gson gson = new Gson();

  /**
   * Responds to any HTTP request related to link previews.
   *
   * @param request An HTTP request context.
   * @param response An HTTP response context.
   */
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
    String url = event.getAsJsonObject("docs")
        .getAsJsonObject("matchedUrl")
        .get("url")
        .getAsString();
    URL parsedURL = new URL(url);
    // If the event object URL matches a specified pattern for preview links.
    if ("example.com".equals(parsedURL.getHost())) {
      if (parsedURL.getPath().startsWith("/support/cases/")) {
        response.getWriter().write(gson.toJson(caseLinkPreview(parsedURL)));
        return;
      }
    }

    response.getWriter().write("{}");
  }


  /**
   * A support case link preview.
   *
   * @param url A matching URL.
   * @return The resulting preview link card.
   */
  JsonObject caseLinkPreview(URL url) throws UnsupportedEncodingException {
    // Parses the URL and identify the case details.
    Map<String, String> caseDetails = new HashMap<String, String>();
    for (String pair : url.getQuery().split("&")) {
        caseDetails.put(URLDecoder.decode(pair.split("=")[0], "UTF-8"), URLDecoder.decode(pair.split("=")[1], "UTF-8"));
    }

    // Builds a preview card with the case name, and description
    // Uses the text from the card's header for the title of the smart chip.
    JsonObject cardHeader = new JsonObject();
    String caseName = String.format("Case %s", caseDetails.get("name"));
    cardHeader.add("title", new JsonPrimitive(caseName));

    JsonObject textParagraph = new JsonObject();
    textParagraph.add("text", new JsonPrimitive(caseDetails.get("description")));

    JsonObject widget = new JsonObject();
    widget.add("textParagraph", textParagraph);

    JsonArray widgets = new JsonArray();
    widgets.add(widget);

    JsonObject section = new JsonObject();
    section.add("widgets", widgets);

    JsonArray sections = new JsonArray();
    sections.add(section);

    JsonObject previewCard = new JsonObject();
    previewCard.add("header", cardHeader);
    previewCard.add("sections", sections);

    JsonObject linkPreview = new JsonObject();
    linkPreview.add("title", new JsonPrimitive(caseName));
    linkPreview.add("previewCard", previewCard);

    JsonObject action = new JsonObject();
    action.add("linkPreview", linkPreview);

    JsonObject renderActions = new JsonObject();
    renderActions.add("action", action);

    return renderActions;
  }

}