Coding level: Intermediate
Duration: 30 minutes
Project type: Google Workspace Add-on
Objectives
- Understand what the add-on does.
- Understand how to build an add-on using Apps Script, and understand what the Apps Script services do.
- Set up your environment.
- Set up the script.
- Run the script.
About this Google Workspace Add-on
In this sample, you create an Google Workspace Add-on that previews links from Google Books in a Google Docs document. When you type or paste a Google Books URL into a document, the add-on recognizes the link and triggers a link preview. To preview the link, you can convert the link into a smart chip and hover over the link to view a card that displays more information about the book.
This add-on uses Apps Script's UrlFetch Service to connect to the Google Books API and get information about Google Books to display in Google Docs.
How it works
In the Google Workspace Add-on's manifest
file, the script configures
the add-on to extend Google Docs and trigger link
previews for URLs that match certain patterns from the Google Books website
(https://books.google.com
).
In the code file, the script connects to the Google Books API and uses the URL
to get information about the book (which is an instance of the Volume
resource). The
script uses this information to generate a smart chip that displays the book's
title and a preview card that displays a summary, the page count, an image of
the book cover, and number of ratings.
Apps Script services
This add-on uses the following services:
- UrlFetch service–Connects to the Google Books
API to get information about books (which are instances of the API's
Volume
resource). - Card service–Creates the user interface of the add-on.
Prerequisites
To use this sample, you need the following prerequisites:
- A Google Account (Google Workspace accounts might require administrator approval).
A web browser with access to the internet.
A Google Cloud project with an associated billing account. Refer to Enable billing for a project.
Set up your environment
Open your Cloud project in the Google Cloud console
If it's not open already, open the Cloud project that you intend to use for this sample:
- In the Google Cloud console, go to the Select a project page.
- 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.
Turn on the Google Books API
This add-on connects to the Google Books API. Before using Google APIs, you need to turn them on in a Google Cloud project. You can turn on one or more APIs in a single Google Cloud project.
In your Cloud project, turn on the Books API.
Configure the OAuth consent screen
This add-on requires a Cloud project with a configured consent screen. Configuring the OAuth consent screen defines what Google displays to users and registers your app so that you can publish it later.
- In the Google Cloud console, go to Menu > APIs & Services > OAuth consent screen.
- Select the user type for your app, then click Create.
- Complete the app registration form, then click Save and Continue.
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.
- If you selected External for user type, add test users:
- Under Test users, click Add users.
- Enter your email address and any other authorized test users, then click Save and Continue.
- Review your app registration summary. To make changes, click Edit. If the app registration looks OK, click Back to Dashboard.
Get an API key for the Google Books API
- Go to the Google Cloud console. Make sure your billing-enabled project is open.
In the Google Cloud console, go to Menu > APIs & Services > Credentials.
Click Create credentials > API key.
Take note of your API key for use in a later step.
Set up the script
Create the Apps Script project
- Click the following button to open the Preview links from Google Books Apps Script project.
Open the project - Click Overview.
- On the overview page, click
Make a copy.
- In your copy of the Apps Script project, go to the
Code.gs
file and replaceYOUR_API_KEY
with the API key that you generated in the previous section.
Copy the Cloud project number
- Go to your Cloud project in the Google Cloud console.
- Click Settings and Utilities > Project settings.
- Copy the Project number.
Set the Apps Script project's Cloud project
- In your Apps Script project,
click
Project Settings.
- Under Google Cloud Platform (GCP) Project, click Change project.
- In GCP project number, paste the Google Cloud project number.
- Click Set project.
Test the add-on
Install a test deployment
- In your Apps Script project, click Editor.
- Open the
Code.gs
file and click Run. When prompted, authorize the script. - Click Deploy > Test deployments.
- Click Install > Done.
Preview a link in Google Docs
- Create a Google Docs document at docs.new.
- Paste the following URL to the document, and press the tab key to
convert the URL into a smart chip:
https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
- Hold the pointer over the smart chip, and when prompted, authorize access to execute the add-on. The preview card displays information about the book.
The following image shows the link preview:
Review the code
To review the Apps Script code for this add-on, click View source code below: