Build a Google Workspace add-on with Node.js

Create Google Workspace add-ons in Cloud Functions using the Node.js runtime.

Objectives

Set up your environment.
Create and deploy a Cloud Function.
Create and deploy the add-on.
Install the add-on.

Prerequisites

A Google Cloud project .
Make sure that you turn on billing for your Cloud project. Learn how to verify the billing status of your projects .
The Cloud SDK is configured with the Cloud project.

Set up your environment

Open your Cloud project in the Google Cloud console

In the Google Cloud console, go to the Select a project page.
Select a Cloud project
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 .

Configure the OAuth consent screen

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

In the Google Cloud console, go to Menu > Google Auth platform > Branding .
Go to Branding
If you have already configured the Google Auth platform, you can configure the following OAuth Consent Screen settings in Branding , Audience , and Data Access . If you see a message that says Google Auth platform not configured yet , click Get Started :

Under App Information , in App name , enter a name for the app.
In User support email , choose a support email address where users can contact you if they have questions about their consent.
Click Next .
Under Audience , select Internal .
Click Next .
Under Contact Information , enter an Email address where you can be notified about any changes to your project.
Click Next .
Under Finish , review the Google API Services User Data Policy and if you agree, select I agree to the Google API Services: User Data Policy .
Click Continue .
Click Create .

For now, you can skip adding scopes. In the future, when you create an app for use outside of your Google Workspace organization, you must change the User type to External . Then add the authorization scopes that your app requires. To learn more, see the full Configure OAuth consent guide.

Create and deploy a Cloud Function

From the Google Cloud console, click Activate Cloud Shell.

Activate Cloud Shell

The Cloud Shell Terminal opens and launches a session in the bottom pane of the Google Cloud console.
Click Authorizeto provision and connect to Cloud Shell.

In the Cloud Shell Terminal, turn on the Cloud Functions API, the Cloud Build API, the Google Workspace add-ons API, and the Compute Engine API:

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

Launch the Cloud Shell Editor by clicking Open Editoron the toolbar of the Cloud Shell window.

This built-in code editor provides the convenience of viewing and editing files in the same environment where projects are built and deployed.

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

  /** 
 * Cloud Function that loads the homepage for a 
 * Google Workspace add-on. 
 * 
 * @param {Object} req Request sent from Google 
 * @param {Object} res Response to send back 
 */ 
 exports 
 . 
 loadHomePage 
  
 = 
  
 function 
  
 addonsHomePage 
  
 ( 
 req 
 , 
  
 res 
 ) 
  
 { 
  
 res 
 . 
 send 
 ( 
 createAction 
 ()); 
 }; 
 /** Creates a card with two widgets. */ 
 function 
  
 createAction 
 () 
  
 { 
  
 return 
  
 { 
  
 "action" 
 : 
  
 { 
  
 "navigations" 
 : 
  
 [ 
  
 { 
  
 "pushCard" 
 : 
  
 { 
  
 "header" 
 : 
  
 { 
  
 "title" 
 : 
  
 "Cats!" 
  
 }, 
  
 "sections" 
 : 
  
 [ 
  
 { 
  
 "widgets" 
 : 
  
 [ 
  
 { 
  
 "textParagraph" 
 : 
  
 { 
  
 "text" 
 : 
  
 "Your random cat:" 
  
 } 
  
 }, 
  
 { 
  
 "image" 
 : 
  
 { 
  
 "imageUrl" 
 : 
  
 "https://cataas.com/cat" 
  
 } 
  
 } 
  
 ] 
  
 } 
  
 ] 
  
 } 
  
 } 
  
 ] 
  
 } 
  
 }; 
 }

In the same directory, create the file package.json with the following sample code:

  { 
  
 "dependencies" 
 : 
  
 { 
  
 "@google-cloud/functions-framework" 
 : 
  
 "^3.0.0" 
  
 } 
 }

Return to the Cloud Shell Terminal by clicking Open Terminal.

Add the Cloud Build Service Account role ( roles/cloudbuild.builds.builder ) to the Compute Engine default service account.

First, setup the service account permission:

  export 
  
 PROJECT_ID 
 = 
 $( 
gcloud  
config  
get  
project ) 
 export 
  
 SERVICE_ACCOUNT_NAME 
 = 
 $( 
gcloud  
compute  
project-info  
describe  
 \ 
  
--format = 
 "value(defaultServiceAccount)" 
 )

Next, grant the missing service account permission:

 gcloud  
projects  
add-iam-policy-binding  
 $PROJECT_ID 
  
 \ 
  
--member = 
 "serviceAccount: 
 $SERVICE_ACCOUNT_NAME 
 " 
  
 \ 
  
--role = 
 "roles/cloudbuild.builds.builder"

Run the following command to deploy the function:
```
 gcloud  
functions  
deploy  
loadHomePage  
--runtime  
nodejs22  
--trigger-http 
```
If prompted, specify that you don't allow unauthenticated invocations of the function. It might take a couple minutes for the function to deploy.

Create an add-on deployment

Find the service account email for the add-on:

 gcloud  
workspace-add-ons  
get-authorization

Grant the service account the cloudfunctions.invoker role. Replace SERVICE_ACCOUNT_EMAIL with the serviceAccountEmail field from the previous step.

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

Get the URL of the deployed function. To get the URL, run the following command and look for the url field under the httpsTrigger section:
```
 gcloud  
functions  
describe  
loadHomePage 
```
Return to the Cloud Shell Editor by clicking Open Editor.

In the same directory as package.json , 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/gmail.addons.execute" 
 ], 
  
 "addOns" 
 : 
  
 { 
  
 "common" 
 : 
  
 { 
  
 "name" 
 : 
  
 "My HTTP Add-on" 
 , 
  
 "logoUrl" 
 : 
  
 "https://raw.githubusercontent.com/webdog/octicons-png/main/black/beaker.png" 
 , 
  
 "homepageTrigger" 
 : 
  
 { 
  
 "runFunction" 
 : 
  
 " URL 
" 
  
 } 
  
 }, 
  
 "gmail" 
 : 
  
 {}, 
  
 "drive" 
 : 
  
 {}, 
  
 "calendar" 
 : 
  
 {}, 
  
 "docs" 
 : 
  
 {}, 
  
 "sheets" 
 : 
  
 {}, 
  
 "slides" 
 : 
  
 {}, 
  
 "httpOptions" 
 : 
  
 { 
  
 "granularOauthPermissionSupport" 
 : 
  
 "OPT_IN" 
  
 } 
  
 } 
 }

Return to the Cloud Shell Terminal to create the deployment:

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

Install the add-on

Install the deployment in development mode:

 gcloud  
workspace-add-ons  
deployments  
install  
quickstart

Open or reload Gmail to view the add-on. In the toolbar on the right, look for a beaker icon.
Click the icon to open the add-on. If prompted, authorize the add-on.

Optional: Clean up

To avoid incurring charges to your account, delete the resources that you created:

Uninstall the add-on from your Google Account:

 gcloud  
workspace-add-ons  
deployments  
uninstall  
quickstart

To avoid incurring charges for the resources used in this quickstart, delete the Cloud project:
```
 gcloud  
projects  
delete  
 PROJECT_ID 
 
```
Replace PROJECT_ID with the ID of the Cloud project that you used for the quickstart. You can find the Cloud project ID in the Google Cloud console on the Dashboard page .

To add more features to your Google Workspace add-on, refer to the following: