Tag Archives: Apps Script

Monitoring the Apps Script issue tracker…with Apps Script

Posted by Paul McReynolds, Product Manager (@pauljmcr), Apps Script and Wesley Chun (@wescpy), Developer Advocate, G Suite

Apps Script is just as popular inside Google as it is among external users and developers. In fact, there are more than 70,000 weekly active scripts written by thousands of Googlers. One of our many uses for Apps Script at Google is to automate and monitor our internal issue tracker.

Your business depends on Apps Script...so does ours 

In spring of this year, we migrated our G Suite issue trackers to a new system based on our internal tracker. This carries a lot of benefits, including improving our ability to track how issues reported from outside of Google relate to bugs and features we’re working on internally. We also have an internal Apps Script API that talks to our issue tracker, which we can now use to work with issues reported from outside of Google.

As soon as the migration was finished, we put Apps Script to work monitoring…itself. Now we have a script in place that monitors Apps Script issues as they are reported and upvoted on the public tracker. When we see an issue that’s having widespread or sudden impact, the script generates an alert that we can then investigate. With the help of our large, active community of developers, and leveraging Apps Script, we’re now able to identify and respond to issues more quickly.

There’s no substitute for independent monitoring, and our Apps Script-based approach isn’t the first or the last line of defense. Instead, this new script helps us catch anything that our monitoring systems miss by listening to what developers are saying on the tracker.

If you see something, say something 

Please help us keep Apps Script humming! When you notice a problem, search the issue tracker for it and file an issue if it's new. Click the star to let us know you’re affected and leave a comment with instructions to reproduce, along with any other relevant details. Those instructions and other details help us respond to the issues more effectively, so please be sure to include them.

Happy scripting!

Stackdriver Logging for Google Apps Script is now available

Posted by Paul McReynolds, Product Manager, Google Apps Script and Romain Vialard, Product Manager, Revevol

Google Apps Script has always provided a simple logging tool—the Logger service—to help developers better test their scripts. This works for many simple use cases, but developers need other ways to log messages and errors, particularly when:
  • Troubleshooting or analyzing scripts across multiple executions
  • Working on a script or add-on with multiple users 
  • Looking for trends or insights about their scripts and users
To make Apps Script a friendlier environment for developers, we are announcing general availability of a new integration with Google Stackdriver. This is in addition to the pre-existing Logger service, which is still available.

Using Stackdriver Logging in Google Apps Script

Log messages can now be sent to Stackdriver Logging using the familiar console.log(), console.info(), etc. functions. You can also instruct Apps Script to log messages and stack traces for all exceptions, which also become available for analysis in Stackdriver Error Reporting by simply checking a box. No need to add a single extra line of code.

In Stackdriver, logs are kept for 7 days for free, and the premium tier offers 30-day retention. Powerful search and filtering are available to quickly find log entries by text content or metadata, and developers can also choose to export logs to BigQuery, Cloud Storage, and Cloud Pub/Sub for further analysis, long term conservation, and custom workflows.

Log messages and errors are reported for all users of a script, with a unique but obfuscated identifier assigned to each user. This means log entries can be aggregated anonymously per user, for example allowing developers to count unique users impacted by an issue or analyze user behavior, but without logging users’ personally identifying information.


Developers get some of these aggregated analyses for free. In the Stackdriver Error Reporting tab of the developer console, you can see recurring errors and the numbers of users impacted. You can even subscribe to receive an email alert when a new type of error is detected.


How developers are using Stackdriver Logging

Developers of scripts and add-ons have started to rely more on more on this new logging capability. Romain Vialard, creator of Yet Another Mail Merge, a popular Google Sheets add-on, is using Stackdriver Logging to time the execution of his add-on, exporting data to BigQuery to perform aggregations and analyze trends. Read this tutorial to learn how to export logs to BigQuery and run queries to analyze how users are interacting with your script.

Stackdriver Logging is one of the ways we’re making Apps Script a more manageable platform for developers. We hope that it and other features coming soon make Apps Script developers more productive and their scripts, add-ons and integrations more robust.

You can read more about how to enable and use the Stackdriver integration by reading Apps Script’s logging documentation.

About the authors 

Romain Vialard is a Google Developer Expert. After some years spent as a consultant, he is now focused on products for G Suite (formerly Google Apps) users, including add-ons such as Yet Another Mail Merge and Form Publisher.

Paul McReynolds is a Product Manager at Google focused on Apps Script and G Suite Marketplace. Previously a startup founder and CTO, Paul believes that the easy things need to be easy or the hard things don’t get done. At Google, he's excited to be a part of the company that makes solving problems for business fun again.

Editor's note: Yet Another Mail Merge and Form Publisher are not created, sponsored, or supported by Google.

Google I/O session recap: how to build custom apps with App Maker

Posted by Geva Rechav, Product Manager, App Maker

Every company has workflows and processes that are unique to its business, customers and employees. Often, these are captured manually within large spreadsheets or ad-hoc databases with macros and scripts. But what if they could be turned into custom business apps instead? Apps that provide useful UIs and distinct user roles, while helping to minimize data entry errors and increase productivity?

This year at Google I/O, I shared reasons why businesses should use App Maker—our low-code, application development tool that lets companies quickly build custom apps in G Suite. Check it out here:


And for those who’d like more detail, here is a recap of my presentation.

Closing enterprise “app gaps” with App Maker 

“App gaps” are a reality for most companies, even those that embrace major SaaS products. Think about the edge cases that aren’t addressed with a standard CRM offering like conducting territory planning or tracking asset performance.

We experienced similar gaps at Google. A few years ago, our HR recruiters were overwhelmed with the thousands of monthly interviews that each generated lengthy feedback reports from multiple interviewers. This volume made it difficult for hiring committees to calibrate candidates and make timely decisions, and resulted in delayed responses. To fix this, our IT team decided to build an app by cobbling elements from our own infrastructure.

Over time, more app requests came in from other parts of Google, so we created App Maker. What started as a handful of apps within Google, evolved into nearly 400 internal apps used by thousands. Plus, the majority of these apps were built by non-engineers outside of IT.

Today, App Maker gives software engineers and citizen developers—like business analysts or coding enthusiasts—the ability to quickly build and deploy apps to get around their workflow challenges.

How does it work? 

App Maker makes it easy to build apps in days, not months, because of its easy data-binding and drag-and-drop UI design. You can also integrate your apps with various data sources, Google services or APIs to cover broad legacy assets. Any app you create is also a part of Drive in G Suite so your data never leaves your domain.

Here’s how to build an App Maker app in three steps:
  1. Define your data models, by importing existing Google Sheets to App Maker, connecting to Google Cloud SQL instances, or manually defining custom objects field by field.
  2. Build your UI by adding pre-built components like data entry forms, report templates and easily create event triggers and application flows. 
  3. Optionally, add open source HTML, CSS and JavaScript to run on the client UI and on the app server, implementing custom functionality that’s not provided out-of-the-box.
App Maker is currently in Early Adopter Program (EAP) for every G Suite Business customer. To get started, apply here.

Ideas to get started 

By now you’re probably wondering what you can build. Well, based on our customers’ experience, here are some good starting points:
  • If you have a large Sheet with more than a handful of users updating it regularly: Sheets usually have an underlying workflow. An App Maker app will provide a better UI for it—showing the workflow visually, prompting for actions and eliminating data entry errors. 
  • If you perform recurring bulk operations in Calendar or Gmail: Say an employee joins or leaves a department, you can build an App Maker app to generate the appropriate bulk-operations in a few clicks. 
  • If your company is already using Apps Script and BigQuery: This means you’ve already invested in customizing workflows. App Maker can increase the velocity of developing custom apps.
Go build your apps with App Maker in G Suite—sign up for the EAP today.

Using Google Sheets filters in Add-ons with Google Apps Script

Posted by Bruce Mcpherson and Romain Vialard, Google Developers Experts, and posted by Wesley Chun (@wescpy), G Suite Developer Advocate

Developers using Google Apps Script can now access the richer feature set of the updated Google Sheets API with the recent launch of the Advanced Sheets Service. One key benefit of using an advanced service vs. native Apps Script objects, is that developers can access current API features (without having to wait for native support to come along). For example, the advanced service allows developers to access Sheets filters which make Add-ons more engaging.

Filter functionality 

With the Sheets API, developers can already get filtered rows or set new filters on Sheets data. With the Advanced Sheet Service, developers can now have their Add-ons respect those filters and apply new filters to modify what data is visible in the Sheets UI. Plus, with any of the Apps Script advanced services, you can easily access the Sheets and other Google APIs without using the UrlFetch service nor managing the authorization flow that you’d otherwise have to perform if using the REST API directly. The snippet below will return the indexes of the filtered rows in a given Sheet. Note that it is also possible to retrieve the list of rows hidden manually, using the "hide row" menu item in Google Sheets, as indicated in the API documentation. In the code sample here, we’re only exposing rows hidden by filter. 

 function getIndexesOfFilteredRows(ssId, sheetId) {
  var hiddenRows = [];
  
  // limit what's returned from the API
  var fields = "sheets(data(rowMetadata(hiddenByFilter)),properties/sheetId)";
  var sheets = Sheets.Spreadsheets.get(ssId, {fields: fields}).sheets;  
  
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].properties.sheetId == sheetId) {
      var data = sheets[i].data;
      var rows = data[0].rowMetadata;
      for (var j = 0; j < rows.length; j++) {
        if (rows[j].hiddenByFilter) hiddenRows.push(j);
      }
    }
  }
  return hiddenRows;
} 
The fields parameter in the code snippet limits what's returned in the Sheets API response, requesting only the values that matter to your app. For more information, check out this page in the Sheets API doc or this recent video on field masks.

See how some Add-ons use filtering 

There are a number of Add-ons that use advanced filtering in Sheets. Here are some good examples:
  • Yet Another Mail Merge: this Add-on helps users send email campaigns from a spreadsheet and is built to process only the filtered rows of a Sheet. Let's say you have a list of people who are registered for an event, but you've only accepted some of these registrants and need to send an email confirmation. With Yet Another Mail Merge and the updated API, you can filter out people you don't approve to attend and the Add-ons skips them without sending confirmations.
  • Sankey Snip and Chord Snip: these Add-ons helps users create special chart types that aren't available in the Google Sheets UI. When respecting filters is enabled with these Add-ons, the charts will dynamically visualize filtered data. Check out the example below from the Chord Snip Add-on.
Of course the API also provides the ability to add, update or delete filters on a Sheet. This is useful if you want to quickly display rows with a specific status to your users. One example would be if you built a workflow approval Add-on. You can show the user rows that are waiting for approval. The snippet below applies the requested filter on a given Sheet—the API documentation describes a standard basic filter object: 

function setSheetBasicFilter(ssId, BasicFilterSettings) {
  //requests is an array of batchrequests, here we only use setBasicFilter
  var requests = [
    {
      "setBasicFilter": {
        "filter": BasicFilterSettings
      }
    }
  ];
  Sheets.Spreadsheets.batchUpdate({'requests': requests}, ssId);
}

Yet Another Mail Merge, as many mass-mailing tools do, keeps track of all emails sent, opened and clicked. A tracking report is available in the spreadsheet sidebar, and clicking on the number of emails opened will automatically apply a filter to display only the matching rows—all rows with the status “opened.”

Now, you can determine filters applied in a Sheet directly through the Sheets API or through Apps Script apps and Add-ons using the Advanced Sheets Service, and continue to build the best experience for your users.

About the Authors 

Romain Vialard is a Google Developer Expert. After some years spent as a G Suite consultant, he is now focused on products for G Suite and Google Apps users, including add-ons such as Yet Another Mail Merge and Form Publisher.

Bruce Mcpherson is a Google Developer Expert, an independent consultant, blogger and author of Going GAS, Google Apps Script for Beginners, and Google Apps Script for Developers.

A new issue tracker for G Suite developers

Posted by Ryan Roth, Developer Programs Engineer and Wesley Chun, Developer Advocate, G Suite
You may have read recently that the Google Cloud Platform team upgraded to Issue Tracker, the same system that Google uses internally. This allows for improved collaboration between all of us and all of you. Issues you file will have better exposure internally, and you get improved transparency in terms of seeing the issues we’re actively working on. Starting today, G Suite developers will also have a new issue tracker to which we’ve already migrated existing issues from previous systems. Whether it’s a bug that you’ve found, or if you wish to submit a favorite feature request, the new issue tracker is here for you. Heads up, you need to be logged in with your Google credentials to view or update issues in the tracker.
The new issue tracker for G Suite developers. 

Each G Suite API and developer tool has its own “component” number that you can search. For your convenience, below is the entire list. You may browse for issues relevant to the Google APIs that you’re using, or click on the convenience links to report an issue or request a new/missing feature:
To get started, take a look at the documentation pages, as well as the FAQ. For more details, be sure to check out the Google Cloud Platform announcement, too. We look forward to working more closely with all of you soon!

G Suite Developer Sessions at Google Cloud Next 2017

Originally posted on the G Suite Developers Blog

Posted by Wesley Chun (@wescpy), Developer Advocate, G Suite

There are over 200 sessions happening next month at Google Cloud's Next 2017 conferencein San Francisco... so many choices! Along with content geared towards Google Cloud Platform, this year features the addition of G Suite so all 3 pillars of cloud computing (IaaS, PaaS, SaaS) are represented!


There are already thousands of developers including Independent Software Vendors (ISVs) creating solutions to help schools and enterprises running the G Suite collaboration and productivity suite (formerly Google Apps). If you're thinking about becoming one, consider building applications that extend, enhance, and integrate G Suite apps and data with other mission critical systems to help businesses and educational institutions succeed.


Looking for inspiration? Here's a preview of some of the sessions that current and potential G Suite developers should consider:


The first is intro blog post & video for the latest Google Sheets API as well as the intro blog post & video for the Google Slides API. Part of the talk also covers Google Apps Script, the Javascript-in-the-cloud solution that gives developers programmatic access to authorized G Suite data along with the ability to connect to other Google and external services.


If that's not enough Apps Script for you, or you're new to that technology, swing by to hear its Product Manager give you an introduction in his talk, quick intro video to give you an idea of what you can do with it!


Did you know that Apps Script also powers "add-ons" which extend the functionality of Google Docs, Sheets, and Forms? Then come to "the G Suite Marketplace where administrators or employees can install your add-ons for their organizations.


In addition to Apps Script apps, all your Google Docs, Sheets, and Slides documents live in Google Drive. But did you know that Drive is not just for individual file storage? Hear directly from a Drive Product Manager on how you can, "the Drive API and Team Drives, you can extend what Drive can do for your organization. One example from the most recent Google I/O tells the story of how WhatsApp used the Drive API to back up all your conversations! To get started with your own Drive API integration, check out this blog post and short video. Confused by when you should use Google Drive or Google Cloud Storage? I've got an app, err video, for that too! :-)


Not a software engineer but still code as part of your profession? Want to build a custom app for your department or line of business without having to worry about IT overhead? You may have heard about Google App Maker, our low-code development tool that does exactly that. Curious to learn more about it? Hear directly from its Product Manager lead in his talk entitled, "

All of these talks are just waiting for you at Next, the best place to get your feet wet developing for G Suite, and of course, the Google Cloud Platform. Start by checking out the session schedule. Next will also offer many opportunities to meet and interact with industry peers along with representatives from all over Google who love the cloud. Register today and see you in San Francisco!




G Suite Developer Sessions at Google Cloud Next 2017

Posted by Wesley Chun (@wescpy), Developer Advocate, G Suite

There are over 200 sessions happening next month at Google Cloud's Next 2017 conferencein San Francisco... so many choices! Along with content geared towards Google Cloud Platform, this year features the addition of G Suite so all 3 pillars of cloud computing (IaaS, PaaS, SaaS) are represented!


There are already thousands of developers including Independent Software Vendors (ISVs) creating solutions to help schools and enterprises running the G Suite collaboration and productivity suite (formerly Google Apps). If you're thinking about becoming one, consider building applications that extend, enhance, and integrate G Suite apps and data with other mission critical systems to help businesses and educational institutions succeed.


Looking for inspiration? Here's a preview of some of the sessions that current and potential G Suite developers should consider:


The first is intro blog post & video for the latest Google Sheets API as well as the intro blog post & video for the Google Slides API. Part of the talk also covers Google Apps Script, the Javascript-in-the-cloud solution that gives developers programmatic access to authorized G Suite data along with the ability to connect to other Google and external services.


If that's not enough Apps Script for you, or you're new to that technology, swing by to hear its Product Manager give you an introduction in his talk, quick intro video to give you an idea of what you can do with it!


Did you know that Apps Script also powers "add-ons" which extend the functionality of Google Docs, Sheets, and Forms? Then come to "the G Suite Marketplace where administrators or employees can install your add-ons for their organizations.


In addition to Apps Script apps, all your Google Docs, Sheets, and Slides documents live in Google Drive. But did you know that Drive is not just for individual file storage? Hear directly from a Drive Product Manager on how you can, "the Drive API and Team Drives, you can extend what Drive can do for your organization. One example from the most recent Google I/O tells the story of how WhatsApp used the Drive API to back up all your conversations! To get started with your own Drive API integration, check out this blog post and short video. Confused by when you should use Google Drive or Google Cloud Storage? I've got an app, err video, for that too! :-)


Not a software engineer but still code as part of your profession? Want to build a custom app for your department or line of business without having to worry about IT overhead? You may have heard about Google App Maker, our low-code development tool that does exactly that. Curious to learn more about it? Hear directly from its Product Manager lead in his talk entitled, "

All of these talks are just waiting for you at Next, the best place to get your feet wet developing for G Suite, and of course, the Google Cloud Platform. Start by checking out the session schedule. Next will also offer many opportunities to meet and interact with industry peers along with representatives from all over Google who love the cloud. Register today and see you in San Francisco!




Increased account security via OAuth 2.0 token revocation

Originally posted on Google Apps Developers Blog

Posted by Michael Winser, Product Lead, Google Apps and Wesley Chun, Developer Advocate, Google Apps

Last week, we clarified the expectations and responsibilities when accessing Google user data via OAuth 2.0. Today, we’re announcing that in order to better protect users, we are increasing account security for enterprise Gmail users effective October 5, 2016. At this time, a new policy will take effect whereby users in a Google Apps domain, while changing their passwords on or after this date, will result in the revocation of the OAuth 2.0 tokens of apps that access their mailboxes using Gmail-based authorization scopes. Please note that users will not notice any specific changes on this date and their applications will continue to work. It is only when a user changes their password from that point moving forward that their Gmail-related tokens become invalid.

Developers should modify their applications to handle HTTP 400 or 401 error codes resulting from revoked tokens and prompt their users to go through the OAuth flow again to re-authorize those apps, such that they can access the user’s mailbox again (additional details below). Late last year, we announceda similar, planned change to our security policy that impacted a broader set of authorization scopes. We later decidednot to move forward with that change for Apps customers and began working on a less impactful update as described above.

What is a revoked token?

A revoked OAuth 2.0 token no longer provides access to a user’s resources. Any attempt to use a revoked token in API calls will result in an error. Any existing token strings will no longer have any value and should be discarded. Applications accessing Google APIs should be modified to handle failed API calls.

Token revocation itself is not a new feature. Users have always been able to revoke access to applications in Security Checkup, and Google Apps admins have the ability to do the same in the Admin console. In addition, tokens that were not used for extended periods of time have always been subject to expiration or revocation. This change in our security policy will likely increase the rate of revoked tokens that applications see, since in some cases the process will now take place automatically.

What APIs and scopes are impacted?

To achieve the security benefits of this policy change with minimal admin confusion and end-user disruption, we’ve decided to limit its application to mail scopes only and to exclude Apps Script tokens. Apps installed via the Google Apps Marketplace are also not subject to the token revocation. Once this change is in effect, third-party mail apps like Apple Mail and Thunderbird―as well as other applications that use multiple scopes that include at least one mail scope―will stop accessing data upon password reset until a new OAuth 2.0 token has been granted. Your application will need to detect this scenario, notify the user that your application has lost access to their account data, and prompt them to go through the OAuth 2.0 flow again.

Mobile mail applications are also included in this policy change. For example, users who use the native mail application on iOS will have to re-authorize with their Google account credentials when their password has been changed. This new behavior for third-party mail apps on mobile aligns with the current behavior of the Gmail apps on iOS and Android, which also require re-authorization upon password reset.

How can I determine if my token was revoked?

Both short-lived access tokens and long-lived refresh tokens will be revoked when a user changes their password. Using a revoked access token to access an API or to generate a new access token will result in either HTTP 400 or 401 errors. If your application uses a library to access the API or handle the OAuth flow, then these errors will likely be thrown as exceptions. Consult the library’s documentation for information on how to catch these exceptions. NOTE: because HTTP 400 errors may be caused by a variety of reasons, expect the payload from a 400 due to a revoked token to be similar to the following: 

{
  "error_description": "Token has been revoked.", 
  "error": "invalid_grant"
}

How should my application handle revoked tokens?

This change emphasizes that token revocation should be considered a normal condition, not an error scenario. Your application should expect and detect the condition, and your UI should be optimized for restoring tokens.

To ensure that your application works correctly, we recommend doing the following:

  • Add error handling code around API calls and token refreshes that can detect revoked tokens.
  • Upon detecting a revoked token, disable any application features that rely on Google API access until the user can re-authorize your application. For example, suspend any recurring background jobs that sync data with a Google API which may be affected.
  • Notify the user that access has been revoked and prompt them to re-authorize access to their resources.
    • If your app interacts directly with the user, you will need to prompt the user to re-authorize, i.e., send an email to the user and/or show them an alert the next time they open your application.
    • However, if your app runs independently of the user, say a background app that uses the Gmail API, you'll need to notify the user through email or some other mechanism.
    • Provide a streamlined UI for re-authorizing access. Avoid having users navigate through your application to find the original setting.
    • Note that revoked tokens will result in similar error messages regardless of how the token was revoked. Your messaging should not assume that the token was revoked due to a password change.

If your application uses incremental authorization to accrue multiple scopes in the same token, you should track which features and scopes a given user has enabled. The end result is that if your app requested and obtained authorization for multiple scopes, and at least one of them is a mail scope, that token will be revoked, meaning you will need to prompt your user to re-authorize for all scopes originally granted.

Many applications use tokens to perform background or server-to-server API calls. Users expect this background activity to continue reliably. Since this policy change also affects those apps, this makes prompt notification requesting re-authorization even more important.

What is the timeline for this change?

To summarize, properly configured applications should be expected to handle invalid tokens in general, whether they be from expiration, non-existence, and revocation as normal conditions. We encourage developers to make any necessary changes to give their users the best experience possible. The policy change is planned to take effect on October 5, 2016.

Please see this Help Center article and FAQ for more details and the full list of mail scopes. Moving forward, any additional scopes to be added to the policy will be communicated in advance. We will provide those details as they become available.

Increased account security via OAuth 2.0 token revocation

Posted by Michael Winser, Product Lead, Google Apps and Wesley Chun, Developer Advocate, Google Apps

Last week, we clarified the expectations and responsibilities when accessing Google user data via OAuth 2.0. Today, we’re announcing that in order to better protect users, we are increasing account security for enterprise Gmail users effective October 5, 2016. At this time, a new policy will take effect whereby users in a Google Apps domain, while changing their passwords on or after this date, will result in the revocation of the OAuth 2.0 tokens of apps that access their mailboxes using Gmail-based authorization scopes. Please note that users will not notice any specific changes on this date and their applications will continue to work. It is only when a user changes their password from that point moving forward that their Gmail-related tokens become invalid.

Developers should modify their applications to handle HTTP 400 or 401 error codes resulting from revoked tokens and prompt their users to go through the OAuth flow again to re-authorize those apps, such that they can access the user’s mailbox again (additional details below). Late last year, we announceda similar, planned change to our security policy that impacted a broader set of authorization scopes. We later decidednot to move forward with that change for Apps customers and began working on a less impactful update as described above.

What is a revoked token?

A revoked OAuth 2.0 token no longer provides access to a user’s resources. Any attempt to use a revoked token in API calls will result in an error. Any existing token strings will no longer have any value and should be discarded. Applications accessing Google APIs should be modified to handle failed API calls.

Token revocation itself is not a new feature. Users have always been able to revoke access to applications in Security Checkup, and Google Apps admins have the ability to do the same in the Admin console. In addition, tokens that were not used for extended periods of time have always been subject to expiration or revocation. This change in our security policy will likely increase the rate of revoked tokens that applications see, since in some cases the process will now take place automatically.

What APIs and scopes are impacted?

To achieve the security benefits of this policy change with minimal admin confusion and end-user disruption, we’ve decided to limit its application to mail scopes only and to exclude Apps Script tokens. Apps installed via the Google Apps Marketplace are also not subject to the token revocation. Once this change is in effect, third-party mail apps like Apple Mail and Thunderbird―as well as other applications that use multiple scopes that include at least one mail scope―will stop accessing data upon password reset until a new OAuth 2.0 token has been granted. Your application will need to detect this scenario, notify the user that your application has lost access to their account data, and prompt them to go through the OAuth 2.0 flow again.

Mobile mail applications are also included in this policy change. For example, users who use the native mail application on iOS will have to re-authorize with their Google account credentials when their password has been changed. This new behavior for third-party mail apps on mobile aligns with the current behavior of the Gmail apps on iOS and Android, which also require re-authorization upon password reset.

How can I determine if my token was revoked?

Both short-lived access tokens and long-lived refresh tokens will be revoked when a user changes their password. Using a revoked access token to access an API or to generate a new access token will result in either HTTP 400 or 401 errors. If your application uses a library to access the API or handle the OAuth flow, then these errors will likely be thrown as exceptions. Consult the library’s documentation for information on how to catch these exceptions. NOTE: because HTTP 400 errors may be caused by a variety of reasons, expect the payload from a 400 due to a revoked token to be similar to the following: 

{
  "error_description": "Token has been revoked.", 
  "error": "invalid_grant"
}

How should my application handle revoked tokens?

This change emphasizes that token revocation should be considered a normal condition, not an error scenario. Your application should expect and detect the condition, and your UI should be optimized for restoring tokens.

To ensure that your application works correctly, we recommend doing the following:

  • Add error handling code around API calls and token refreshes that can detect revoked tokens.
  • Upon detecting a revoked token, disable any application features that rely on Google API access until the user can re-authorize your application. For example, suspend any recurring background jobs that sync data with a Google API which may be affected.
  • Notify the user that access has been revoked and prompt them to re-authorize access to their resources.
    • If your app interacts directly with the user, you will need to prompt the user to re-authorize, i.e., send an email to the user and/or show them an alert the next time they open your application.
    • However, if your app runs independently of the user, say a background app that uses the Gmail API, you'll need to notify the user through email or some other mechanism.
    • Provide a streamlined UI for re-authorizing access. Avoid having users navigate through your application to find the original setting.
    • Note that revoked tokens will result in similar error messages regardless of how the token was revoked. Your messaging should not assume that the token was revoked due to a password change.

If your application uses incremental authorization to accrue multiple scopes in the same token, you should track which features and scopes a given user has enabled. The end result is that if your app requested and obtained authorization for multiple scopes, and at least one of them is a mail scope, that token will be revoked, meaning you will need to prompt your user to re-authorize for all scopes originally granted.

Many applications use tokens to perform background or server-to-server API calls. Users expect this background activity to continue reliably. Since this policy change also affects those apps, this makes prompt notification requesting re-authorization even more important.

What is the timeline for this change?

To summarize, properly configured applications should be expected to handle invalid tokens in general, whether they be from expiration, non-existence, and revocation as normal conditions. We encourage developers to make any necessary changes to give their users the best experience possible. The policy change is planned to take effect on October 5, 2016.

Please see this Help Center article and FAQ for more details and the full list of mail scopes. Moving forward, any additional scopes to be added to the policy will be communicated in advance. We will provide those details as they become available.

Announcing Android add-ons for Docs and Sheets

Posted by By Saurabh Gupta, Product Manager, Google Apps

We know many of you consider your mobile device as your primary tool to consume business information, but what if you could use it to get more work done, from anywhere? We’re excited to introduce Android add-ons for Docs and Sheets, a new way for you to do just that—whether it’s readying a contract you have for e-signature from your phone, or pulling in CRM data on your tablet for some quick analysis while waiting for your morning coffee, Android add-ons can help you accomplish more.

Get more done with your favorite third-party apps, no matter where you are

We’ve worked with eight integration partners who have created seamless integrations for Docs and Sheets. Here’s a preview of just a few of them:
  • DocuSign - Trigger or complete a signing process from Docs or Sheets, and save the executed document to Drive. Read more here.
DocuSign lets you easily create signature envelopes right from Google Docs
  • ProsperWorks - Import your CRM data to create and update advanced dashboards, reports and graphs on Sheets, right from your device. Read more here.
  • AppSheet - Create powerful mobile apps directly from your data in Sheets instantly — no coding required. Read more here.
  • Scanbot - Scan your business documents using built-in OCR, and insert their contents into Docs as editable text. Read more here.


You can find these add-ons and many more, including PandaDoc, ZohoCRM, Teacher Aide, EasyBib and Classroom in our Google Play collection as well as directly from the add-on menus in Docs or Sheets.


Try them out today, and see how much more you can do.

Calling all developers: try our developer preview today!

As you can see from above, Android add-ons offer a great opportunity to build innovative integrations and reach Docs and Sheets users around the world. They’re basically Android apps that connect with Google Apps Script projects on the server-side, allowing them to access and manipulate data from Google Docs or Sheets using standard Apps Script techniques. Check out our documentation which includes UI guidelines as well as sample code to get you started. We’ve also made it easy for you to publish your apps with the Apps Script editor.

Android add-ons are available today as a developer preview. We look forward to seeing what you build!