Hide

Develop Add-ons for Google Sheets, Docs, and Forms

Add-ons run inside Google Sheets, Docs, and Forms, but they're built by developers like you. Our new platform lets you add menu items and sidebars, edit files programmatically, and tie into over a dozen Google services without even spinning up a server. This guide will show you everything you need to publish your first add-on to our store for millions to discover.

See what you can make

Add-ons are built with Apps Script, a server-side JavaScript platform that requires zero setup.

Get to know Apps Script

If you're an Apps Script pro, this section will be old hat. For the rest, here's a quick synopsis.

The platform

Apps Script's code editor is a web app that you launch from within Google Sheets, Docs, or Forms. The language is based on JavaScript, but executes on Google's servers rather than directly in the user's browser (with the exception of client-side user interfaces, described below). There's literally nothing you need to install to begin development. For a basic rundown of the platform, read our overview.

Our APIs, and yours

Apps Script's built-in services offer easy-to-use APIs for 11 popular Google Apps, including Calendar, Drive, and Gmail — not to mention more than a dozen utility services to cover common scripting needs. Other Google products, like YouTube, are available as advanced services. Because Apps Script can connect to external APIs, it's simple to integrate your company's services with Google Apps.

Authorization

When a user installs an add-on, Apps Script scans the code to determine which built-in or advanced Google services it uses, then prompts the user to authorize access to their data. If your add-on uses authenticated third-party APIs — including Google APIs that Apps Script doesn't natively support — we provide a callback URL and state token so that you can set up a secondary authorization flow.

User interfaces

Add-ons can create menu items and open dialogs or sidebars. For custom interfaces, the HTML service offers client-side HTML, CSS, and JS with a few limitations: notably, our security sandbox doesn't work with many JS libraries.

Storage

Apps Script offers several ways to store data. The Properties service is great for simple strings, while the JDBC service lets you connect to an external database — the best choice for robust applications.

Logging / debugging

The script editor includes a logger and a debugger that are useful during development, but not once an add-on is published. To track errors that users encounter in the wild, consider writing logs to a database or appending a row to a private spreadsheet. Your add-on's Help menu also lets users submit anonymous bug reports.

Triggers

Triggers let your add-on run when a user takes an action like opening a document or responding to a Google Form. Add-ons can use simple triggers like the special function onOpen(e), installable triggers like form-submit, as well as time-driven triggers that execute code at a particular time or on a recurring interval, as frequently as every hour or as infrequently as once per month. Note that installable triggers behave a little differently in add-ons than in the rest of Apps Script (for one thing, no pesky "Summary of failures" emails!), so be sure to read the documentation.

Understand the development cycle

To create an add-on, you can develop an add-on in a standalone script. While developing, make sure you understand the intricacies of the add-on authorization lifecycle; also make sure your add-on adheres to the UI style guide. When you have a working version, you should test the add-on in other documents. Once your add-on is complete, publish to the store. After that, Google Apps users worldwide — or, if you prefer, just users within your domain — will be able to use your add-on in their own documents.

Things you can't do

There are a few restrictions on what add-ons can do:

Change features in Google Apps

The add-ons framework is designed to enhance Google Sheets, Docs, and Forms — not to add limits. Consequently, you can't alter existing features or lock down the Google Apps sharing model.

Charge users to install

We don't yet provide a way to charge users for add-ons, and add-ons can't include ads. However, you can roll your own payment system or call into an existing billing database.

Detect many events

Except for the triggers described above, Apps Script can't tell what a user does outside the add-on itself. For example, you can't detect when the user clicks on the Google Docs toolbar. It is possible to poll for changes in a file's contents from a sidebar's client-side code, although you'll always have a slight delay. That technique can also alert your script to changes in the user's selected cells (in Sheets) and cursor or selection (in Docs).

Rely on server-side libraries

Using Apps Script libraries will cause your add-on to run more slowly than it would if all the server-side code were contained within a single script project. (Client-side JavaScript libraries like jQuery are just fine, however.) Although server-side libraries technically work in add-ons, we strongly discourage using them; instead, copy the contents of the library into your main script.

Brand it as your own

Look the part

For the best user experience, make sure your interfaces adhere to the add-ons UI guidelines. Also, it's easy to create buttons and other elements that match the rest of Google Apps: just use our CSS package in HTML service.

Serve images

Most add-ons include a logo or other images. These assets aren't packaged with the add-on; instead, your user interfaces reference them just like any other web page would. You can host assets on your own web server or on Google Drive.

Join the Add-ons menu

Unlike other Apps Script projects, add-ons cannot create top-level menus in Sheets, Docs, or Forms. Instead, each add-on gets a spot in the Add-ons menu, including an automatic Help item that lets users send feedback to the developer.

Teach Sheets, Docs, and Forms to dance

Apps Script includes special APIs to let you programmatically create, read, and edit Google Apps files. To build most add-ons, you'll need to be familiar with at least one of these services.

Illustration of Google Sheets editor

Spreadsheet service

The Spreadsheet service treats Google Sheets as a grid, operating with two-dimensional arrays.

Illustration of Google Docs editor

Document service

The Document service interface for Google Docs is similar to the XML document-object model.

Illustration of Google Forms editor

Forms service

The Forms service constructs a Google Form as a list of question items and layout items.

Publish or perish (we recommend publish)

Once your add-on is a working prototype, publish to the store. Note that public add-ons undergo a review process to ensure they meet our content and style guidelines. See you in the store!

Send feedback about...

Apps Script