Preview links in Google Docs quickstart

Create a Google Workspace Add-on that previews links from a third-party service. In this quickstart, you use Cloud Functions and the Node.js runtime to create an add-on that extends Google Docs and lets users preview a link as a smart chip and card.

Objectives

  • Set up your environment.
  • Create and deploy a Cloud Function for link previews.
  • Create and deploy the add-on.
  • Install and test the add-on.

Prerequisites

Set up your environment

Open your Cloud project in the Google Cloud console

  1. In the Google Cloud console, go to the Select a project page.

    Select a Cloud project

  2. Select the Google Cloud project you want to use. Or, click Create project and follow the on-screen instructions. If you create a Google Cloud project, you might need to turn on billing for the project.

Google Workspace Add-ons require a consent screen configuration. Configuring your add-on's OAuth consent screen defines what Google displays to users.

  1. In the Google Cloud console, go to Menu > APIs & Services > OAuth consent screen.

    Go to OAuth consent screen

  2. Select the user type for your app, then click Create.
  3. Complete the app registration form, then click Save and Continue.

  4. For now, you can skip adding scopes and click Save and Continue. In the future, when you create an app for use outside of your Google Workspace organization, you must add and verify the authorization scopes that your app requires.

  5. If you selected External for user type, add test users:
    1. Under Test users, click Add users.
    2. Enter your email address and any other authorized test users, then click Save and Continue.
  6. Review your app registration summary. To make changes, click Edit. If the app registration looks OK, click Back to Dashboard.

Create and deploy a Cloud Function

  1. In a local terminal or Cloud Shell, turn on the Cloud Functions, Cloud Build, and the Add-ons API:

    gcloud services enable cloudfunctions cloudbuild.googleapis.com gsuiteaddons.googleapis.com

  2. In an empty directory, create the file function.js with the following sample code:

    /**
 * Responds to any HTTP request.
 *
 * @param {Object} req HTTP request context.
 * @param {Object} res HTTP response context.
 */
exports.createLinkPreview = (req, res) => {
  res.send(createCatCard(req.body));
}

function createCatCard(event) {
  const url = event.docs.matchedUrl.url.split('/');
  const cat = url[url.length - 1];
  return {
    "action": {
      "linkPreview":
      {
        "title": "Random Cat",
        "previewCard": {
          "header": {
            "title": "Cats!"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Your random " + cat + ":"
                  }
                },
                {
                  "image": {
                    "imageUrl": "https://cataas.com/cat"
                  }
                }
              ]
            }
          ]
        }
      }
    }
  };
}

  3. Deploy the function:

    gcloud functions deploy createLinkPreview --runtime nodejs16 --trigger-http

    If prompted, specify that you do not allow unauthenticated invocations of the function. It might take a couple minutes for the function to deploy.

Create an add-on deployment

  1. Find the service account email for the add-on:

    gcloud workspace-add-ons get-authorization

  2. Grant the service account the cloudfunctions.invoker role with the following sample code. Replace SERVICE_ACCOUNT_EMAIL with the email address from the previous step.

    gcloud functions add-iam-policy-binding createLinkPreview \
    --role roles/cloudfunctions.invoker \
    --member serviceAccount:SERVICE_ACCOUNT_EMAIL

  3. Get the URL of the deployed function:

    gcloud functions describe createLinkPreview

  4. Create the file deployment.json with the following sample code. Replace URL with the URL of the deployed function from the previous step.

    {
  "oauthScopes": [
    "https://www.googleapis.com/auth/documents.readonly"
  ],
  "addOns": {
    "common": {
      "name": "My link preview add-on",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/2x/pets_black_24dp.png",
      "layoutProperties": {
        "primaryColor": "#dd4b39"
      }
    },
    "docs": {
      "linkPreviewTriggers": [{
        "runFunction": "URL",
        "patterns": [{
            "hostPattern": "cataas.com",
            "pathPrefix": "cat"
         }],
         "labelText": "Cat",
         "localizedLabelText": {
           "fr-fr": "Carte de Chat"
         }
       }]
    }
  }
}

  5. Create the deployment:

    gcloud workspace-add-ons deployments create linkpreview \
    --deployment-file=deployment.json

Install and test the add-on

  1. Install the deployment in development mode:

    gcloud workspace-add-ons deployments install linkpreview

  2. To view the add-on, go to Google Docs and open or create a document. To verify that the add-on has been installed, look for the pet icon in the right side panel.

  3. Copy https://cataas.com/cat/tabby and paste the link into the document. When a link preview tooltip appears, press the tab key to convert the link into a smart chip.

  4. To display a preview card of the link, hold the pointer over the smart chip. If prompted, authorize the add-on.

Clean up

  1. Uninstall the add-on from your Google Account:

    gcloud workspace-add-ons deployments uninstall linkpreview

  2. To avoid incurring charges for the resources used in this quickstart, delete the project:

    gcloud projects delete PROJECT_ID

    Replace PROJECT_ID with the ID of the project that you used for the quickstart. You can find the project ID in the Cloud console on the Dashboard page.