This repo contains the boilerplates for gamil add-on and notes for development.

Setup

• create standalone script project, manually switch it to a standard google cloud platform project. For difference of default and standard projects and why/how to migrate, see official guide to cloud platform projects.
• setup clasp.
• install as developer add-on for test, doc here.

Logging and Analytics

If setup a standard google cloud platform project and link to the apps script projetc, use console.log, console.info, console.error, etc, will send log to stackdriver logs automatically.

• each log has a user key attached in "labels" of the log metadata
• can also send customized information such as user id
• enable Log exceptions in apps script project to capture exceptions in large user base.
• Stackdriver Error Reporting - no additional setup is needed for apps script projects

Short-term logging

if log for debugging, can use Logger.log instead of console.log. This will send data to Apps Script Logger, which is lightweight but only persists a short time, more here.

Pricing of Stackdriver Logging

Pricing guide

Card Update and Navigation

• Basic navigation - stack cards together, as in contextualAddOn.buildContextualAddOn
• Custom Navigation, refer to buildButtonCard.btn2OnClickCallback , buildInfoWidgetCard.navToButtonCard, and universalActions.createSettingsResponse

Error handling

use try{...}catch(e){...} to render error handling UI, for example universalActions.showErrorUIexample.

External API

• put external api domain to urlFetchWhitelist field of appsscript.json -- only allow https protocol, and must have trailing slash.
• check buildExternalCard.onConfirmDropdown.

connect to non-google services

UrlFetchApp class

Examle external api used for testing: News API. Need to register and get free API Key.

Contextual triggered and Compose triggered Add-ons

• Cards for contextual and for compose may not be used interchangeably, because the two triggers pass different information to the callbacks.
• UI components are the same.
• Compose trigger event object does not contain accessToken, thus cannot use some GmailApp methods, such as GmailApp.createDraft(). Use Gmail API instead. See example codes in ./compose/composeAddOn.

Examples of implementation

• search threads
• create/modify draft
• send/reply/forward message (can add attachment)
• get message metadata
• create/delete label
• mark message/thread (un)read, (un)important, (un)starred
• (un)trash/(un)spam/(un)archive threads

Note: can also use MailApp to send mail instead of GmailApp, docs.

• Interact with other google services
• Interact with external API

Some reference shortcuts

official doc for add-ons

Manifest structure

gmail scopes(add-on)

gmail scopes

google scopes