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 announced a similar, planned change to our security policy that impacted a broader set of authorization scopes. We later decided not 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:
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.
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!
Posted by Sumit Chatterjee, Product Manager, Google Mobile Management and Wesley Chun, Developer Advocate, Google Apps
As security on mobile devices becomes increasingly important, we want to give Google Apps administrators the visibility to monitor key activities occurring on managed devices in their domain. With that in mind, today we are launching Mobile Audit for Google Apps Unlimited users, which audits activities on iOS and Android devices (using the native iOS Sync and Android Sync protocols) managed by Google Mobile Management. Examples of activities that are recorded include: operating system updates, device settings changes, and mobile application installs, updates and removals.
Google Apps Administrators can also go to the Reports page in the Admin console to see all the Mobile Audit events. Below is an example of what this page looks like querying one user’s activity, including newly registered devices:
As part of this launch, we are excited to make all Mobile Audit events available programmatically through the Admin SDK Reports API via Mobile Audit Activity Events. The Admin SDK is accessible through its REST API or Google Apps Script. With this new feature, administrators will be able to query all of the Mobile Audit information by user, by device, or by event, as well as verify that all of your deployed devices are running the latest security updates. You can even send this information to an asset management system to track all of your mobile inventory.
For example, if we wanted to download all of the newly registered devices, you could make a call like this to the API (via Google Apps Script):
AdminReports.Activities.list('all', 'mobile', { eventName: "DEVICE_REGISTER_UNREGISTER_EVENT", filters: "ACCOUNT_STATE==REGISTERED", maxResults: 1000 });
Once you have the response from the API, you could easily parse through that data, including device models, serial numbers, user email addresses, and any other relevant information to help you track your inventory.
A more critical use case that mobile administrators have been asking for is a way to take proactive actions on devices without requiring manual intervention. For example, a mobile administrator may want to automatically block a device when something suspicious is detected. This new feature enables admins to write simple apps that do just that.
Using the Mobile Audit Activity Events in the Reports API and the Mobile Devices component of the Directory API, administrators can create scheduled scripts to check for devices that are reporting suspicious activity, and then take actions on those devices.
The Apps Script snippet below returns results if there are any mobile audit events for suspicious activity:
var response = AdminReports.Activities.list('all', 'mobile', { eventName: "SUSPICIOUS_ACTIVITY_EVENT", maxResults: 1000 });
If there are results, the code below shows you how to retrieve the unique Google identifier for those devices, via the “RESOURCE_ID” parameter. Note that this snippet only assumes a single device reporting suspicious activity—you’ll need to tweak the code to support more than one.
var parameters = response.items[0].events[0].parameters; var resourceId; for (i = 0; i < parameters.length; i++) { if (parameters[i].name == ‘RESOURCE_ID’) { resourceId = parameters[i].value; break; } }
Now the Directory API can be invoked to block the device that corresponds with the above unique identifier using this Apps Script snippet:
AdminDirectory.Mobiledevices.action('my_customer', resourceId, { action: "block" });
We are really excited to see what uses you have for Mobile Audit in the Reports API. For more information and to get started, please see the Developer Guide, reference documentation, and the Help Center. (NOTE: Again, this feature is available only to our customers with users on the Google Apps Unlimited license.)
Posted by Saurabh Gupta, Product Manager, Google Apps Script
There are two ways to send email in Apps Script: MailApp's sendEmail and GmailApp's sendEmail method. One of the differences between these two methods is that the MailApp’s sendEmail method doesn’t require the developer to be a Gmail user. For example, a Google Apps customer who doesn’t use Gmail, but uses Apps Script instead, can send emails through MailApp but not GmailApp.
Starting on September 13, 2016, users with free public Google Accounts (consumers) and Google Apps for Education and Google Apps Free edition users, will be required to have Gmail access to send messages through Apps Script’s Mail Service. Consumers can enable Gmail on their Google account after signing-in—note your Gmail will then become the primary address of your Google account. Administrators of Google Apps domains (Education and Free edition only) can use the Admin console to turn on Gmail for their domain.
This change does not require any updates to your code. You can continue to use MailApp as before; just make sure that you have signed up for Gmail. We realize that sometimes these changes are disruptive to our developers, but we can assure you that we put lot of care and deliberation into this process.
Posted by Ben Greve, Developer Support Specialist, Google Apps Script
So you’ve started to build an add-on. Congrats! You identified a problem, figured out a solution, and wrote some code to accomplish it like a pro. Now it’s time to focus on design, to make sure your audience understands what your add-on does and how to use it.
In this post, I will outline five simple design tips to help make your add-on a pleasure to use. Don’t worry if you’re not an artist – these are basic concepts that anyone can apply.
Crafting a guided workflow takes the guesswork (and stress) out of using an add-on. Your user should never wonder, ‘What am I supposed to do next?’ Actions, forms, text, and buttons should be designed to create a natural flow guiding the user from one step to the next.
This can be accomplished in a number of ways. Try presenting actions in a natural order: from left to right and from top to bottom (assuming LtR language; adjust as needed). You can indicate which button is the primary action by styling it using the blue .action class. You can guide the user’s behavior by limiting the actions available (sometimes referred to as ‘forcing function’). For example, actions/options with dependencies can be disabled or hidden until they should be used. Another option is to spread a workflow across several pages and require the user to complete a given page before they can proceed to the next.
Complex add-ons require effective communication. Simple add-ons do, too. Effective communication is necessary for your audience to understand what your add-on does and how they should use it.
Use accessible language that anyone can understand. Don’t use complex wording if more easily digestible terminology is available. Unless your target audience has been demanding a feature to “asynchronously call an RPC with dependent proto messages,” you should avoid using unnecessarily technical or jargony language.
Present information when and where it’s needed. Instructions should be displayed in the context which they will be used. Actions should be clearly labeled so that users will know exactly what they do. Provide enough information so the user understands what they are doing, why they are doing it, and where they are going.
Have you ever used an app where you click on a button and nothing happens? You sit there wondering: Did it work? Did it not work? Did anything happen at all? When building your add-on, don’t do this to your users. Make sure that all actions have clear and immediate feedback, so no one is never left wondering, “What just happened?”.
With this in mind, there is still room for graceful design. Feedback can be subtle - it doesn’t need to shout, ‘ACTION 1 COMPLETED’! Leverage nuanced changes, such as displaying a quick message in a toast or moving to the next step in the workflow.
What happens if an action takes a long time to complete? Someone clicks a button and waits… and waits… and waits. A good UI will account for this scenario, too. Try using a loading graphic (i.e. a spinner or a progress bar) and for longer loading times consider including a button to cancel.
People make mistakes. It’s sad but true, and unlikely to change any time soon. Keep your users safe from themselves and design actions to have minimal risk.
The ideal solution is to remove the risk entirely. Inserting a bunch of data into a spreadsheet? Consider creating a new sheet and insert the data there. When appropriate, configure actions to add rather than replace, minimizing potential damage to existing content.
There will be situations where avoiding risk entirely won’t be possible. In these cases, do the best you can to explicitly communicate the action’s effect so your user can make a well-informed decision. A preview or a warning of the impending changes will help ensure that the user is aware of what’s coming. And of course, provide a method to ‘undo’ when possible.
Each UI element in your add-on should serve a purpose; consider removing anything that doesn’t. For the best design, keep it focused on functionality and trim any excess.
Using a large range of styling can actually undermine the power of the design. When a website is covered with different colors, styles, and fonts, it makes it difficult for any styling to communicate a specific meaning. Design patterns that are overly complicated or inconsistent make it difficult for users to learn what’s important and what isn’t.
Instead, consider an app with only three text stylings: one large, one bold, and one plain. The large style is always (and only) used for headers/titles, the bold style is used for labels, and the plain style is normal body text. Any time a user sees one of these, they’ll know exactly what they are looking at. Less is more.
Too many brilliant add-ons and apps have failed due to simple design flaws that made them inaccessible to users. These five tips are intended to help you prevent those common mistakes and provide a foundation for a great user experience.
As you work on your next add-on, remember the five lessons here:
Finally: please make sure to include the necessary onOpen() and onInstall() functions (if you want the add-on to work), follow our UI Style Guide, and use the provided CSS Package.
Have any tips or tricks of your own? Leave a comment below and share your design insights with the rest of the Apps Script community!
Posted by Romain Vialard, a Google Developer Expert and developer of Yet Another Mail Merge, a Google Sheets add-on.
Google Apps Script makes it easy to create and publish add-ons for Google Sheets, Docs, and Forms. There are now hundreds of add-ons available and many are reaching hundreds of thousands of users. Google Analytics is one of the best tools to learn what keeps those users engaged and what should be improved to make an add-on more successful.
Add-ons run inside Google Sheets, Docs, and Forms where they can display content in dialogs or sidebars. These custom interfaces are served by the Apps Script HTML service, which offers client-side HTML, CSS, and JS with a few limitations.
Among those limitations, cookies aren’t persistent. The Google Analytics cookie will be recreated each time a user re-opens your dialog or sidebar, with a new client ID every time. So, Analytics will see each new session as if initiated by a new user, meaning the number of sessions and number of users should be very similar.
Fortunately, it’s possible to use localStorage to store the client ID — a better way to persist user information instead of cookies. After this change, your user metrics should be far more accurate.
Add-ons can also run via triggers, executing code at a recurring interval or when a user performs an action like opening a document or responding to a Google Form. In those cases, there’s no dialog or sidebar, so you should use the Google Analytics Measurement Protocol (see policies on the use of this service) to send user interaction data directly to Google Analytics servers via the UrlFetch service in Google Apps Script.
A Client ID is also required in that case, so I recommend using the Apps Script User properties service. Most examples on the web show how to generate a unique Client ID for every call to Analytics but this won’t give you an accurate user count.
You can also send the client ID generated on client side to the server so as to use the same client ID for both client and server calls to Analytics, but at this stage, it is best to rely on the optional User ID in Google Analytics. While the client ID represents a client / device, the User ID is unique to each user and can easily be used in add-ons as users are authenticated. You can generate a User ID on the server side, store it among the user properties, and reuse it for every call to Analytics (both on the client and the server side).
In add-ons, we usually rely on event tracking and not page views. It is possible to add different parameters on each event thanks to categories, actions, labels and value, but it’s also possible to add much more info by using custom dimensions & metrics.
For example, the Yet Another Mail Merge add-on is mostly used to send emails, and we have added many custom dimensions to better understand how it is used. For each new campaign (batch of emails sent), we record data linked to the user (e.g. free or paying customer, gmail.com or Google for Work / EDU user) and data linked to the campaign (e.g. email size, email tracking activated or not). You can then reuse those custom dimensions inside custom reports & dashboards.
Once you begin to leverage all that, you can get very insightful data. Until October 2015, Yet Another Mail Merge let you send up to 100 emails per day for free. But we’ve discovered with Analytics that most people sending more than 50 emails in one campaign were actually sending 100 emails - all the free quota they could get - but we failed to motivate them to switch to our paid plan.
As a result of this insight, we have reduced this free plan to 50 emails/day and at the same time introduced a referral program, letting users get more quota for free (they still don’t pay but they invite more users so it’s interesting for us). With this change, we have greatly improved our revenue and scaled user growth.
Or course, we also use Google Analytics to track the efficiency of our referral program.
To help you get started in giving you more insight into your add-ons, below are some relevant pages from our documentation on the tools described in this post. We hope this information will help your apps become more successful!:
Romain Vialard profile | website
Romain Vialard is a Google Developer Expert. After some years spent as a Google Apps consultant, he is now focused on products for Google Apps users, including add-ons such as Yet Another Mail Merge and Form Publisher.
Posted by Matt Hessinger, Project Specialist, Google Apps Script
Welcome to our 100th blog post on Apps Script! It’s amazing how far we’ve come from our first post back in 2010. We started out highlighting some of the simple ways that you could develop with the Apps platform. Today, we’re sharing tips and best practices for developing more complex Apps Script solutions by pointing out some community contributions.
The Apps Script editor does not allow you to use your own source code management tool, making it a challenge to collaborate with other developers. Managing development, test, and production versions of a project becomes very tedious. What if you could have the best of both worlds — the powerful integration with Google’s platform that Apps Script offers, along with the development tooling and best practices that you use every day? Now, you can.
npm install -g node-google-apps-script
This project, “node-google-apps-script”, is a Node.js based command-line interface (CLI) that uses Google Drive API to update Apps Script project from the command line. You can view the node package on the NPM site, and also view the GitHub repo. Both links have usage instructions. This tool was created by Dan Thareja, with additional features added by Matt Condon.
Before using the tool, take a look at the Apps Script Importing and Exporting Projects page. There are a few things that you should be aware of as you plan out your development process. There are also a few best practices that you can employ to take full advantage of developing in this approach.
There is a sample project that demonstrates some of the practices described in this post: click here to view that code on GitHub. To get all of the Apps Script samples, including this import/export development example:
Your standalone Apps Script projects live in Google Drive. If you use a command-line interface (CLI) tool like the one linked above, you can work in your favorite editor, and commit and sync code to your chosen repository. You can add tasks in your task runner to push code up to one or more Apps Script projects, conditionally including or excluding code for different environments, checking coding style, linting, minifying, etc. You can more easily create and push UI-related files to a file host outside of Apps Script, which could be useful if those same files are used in other apps you are building.
In addition to the information on the Importing and Exporting Projects page, here are a few things to consider:
Over and above the editing experience, the biggest improvements you get by working outside the script editor is that you are no longer locked into working in just one Apps Script project. You can much more easily collaborate as a team, with individual developers having their own working Apps Script projects, while also having more controlled test, user acceptance and production versions, each with more process and security. Beyond just the consistency with other normal project practices, there are a few Apps Script specific ways you can leverage this multi-environment approach.
If you are going to use this approach, here are three best practices to consider:
The provided sample shows a simple example of how a base configuration class could allow a developer to inject their local values for their own debugging and testing. In this case, the developer also added the annotation @NotOnlyCurrentDoc, which tells Apps Script that they need the full scope for Drive API access. In this project, the “production” deployment has the annotation @OnlyCurrentDoc, which leads to the OAuth scope that is limited to the document associated with script running as Sheets, Docs, or Forms add-on. If you add a standard file pattern to the source project’s “ignore” file, these developer-specific files will never get into the actual codebase.
Benefits for your project — Production can have more limited OAuth scopes, while a developer can use broader access during development. Developers can also have their own personal configuration settings to support their individual development efforts.
While there is no current way to trigger tests in an automated way, you still may want to author unit tests that validate specific functions within your projects. You’ll also likely have specific configuration values for testing. Once again, none of these files should make it into a production deployment. You can even use the Apps Script Execution API to drive those tests from a test runner!
Benefits for your project — You can author test functions, and keep them separate from the production Apps Script file. This slims down your production Apps Script project, and keeps the correct OAuth scopes that are needed for production users.
If you are developing an add-on for Sheets or Docs, and you expect to have an “active” item on the SpreadsheetApp. However when you are developing or testing, you may be running your Apps Script without an “active” context. If you need to develop in this mode, you can wrap the call to get the current active item in a method that also can determine what mode you are running in. This would allow your development or test instance to inject the ID of an “active” document to use for testing, while delegating to the getActive* result when running in a real context.
Benefits for your project — You can integrate better unit testing methodologies into your projects, even if the end deployment state dependents on resources that aren’t typically available when debugging.
You now have the option to use your own development and source management tools. While you still do need to use the Apps Script editor in your application’s lifecycle — to publish as a web app or add-on, configure advanced services, etc. — taking this step will help you get the most out of the power of the Apps Script platform. Remember to check out Apps Script on the Google Developers site to get more information and samples for your Apps Script development.
If you happen to use python tools on the command line to facilitate your team’s build process, you can check out Joe Stump's python-gas-cli. You can view the package info here or the GitHub repo where you’ll also find usage instructions.
Here are some additional reference links related to this post:
Back in December 2014, we announced the IFRAME sandbox mode for HtmlService which has helped improve the speed of an application’s user interface (UI). It also gives users a choice of using a variety of JS libraries on the client. We have been working hard to improve IFRAME sandbox mode and have added many features since then, including: Firefox support, file uploads, top navigation support, and improved Google Picker API support. Since IFRAME sandbox provides faster UIs and has more capabilities than NATIVE and EMULATED modes, developers should only be using IFRAME sandbox mode moving forward.
As of today, both EMULATED and NATIVE modes in HtmlService are deprecated. Over the next few months, we plan on sunsetting both EMULATED and NATIVE modes in stages to give you enough time to migrate your scripts.
We have created a migration guide to help you with this transition. For many scripts, no changes will be needed, unless they use a small set of features described in the migration guide. The guide also describes a few potential breaking changes. It is important that you review all your scripts that use HtmlService to ensure that the switch to IFRAME sandbox mode does not cause them to fail.
Here’s the timeline:
In November 2015, all new scripts will default to IFRAME sandbox mode unless NATIVE mode is explicitly specified. For example, if you make a copy of an existing script, the new script will use IFRAME sandbox mode unless you have explicitly set the sandbox mode to NATIVE.
In December 2015 (see sunset schedule for exact dates), EMULATED mode will be shutdown. Any scripts explicitly using EMULATED mode will default to IFRAME sandbox mode.
On April 28th, 2016, all scripts will default to IFRAME sandbox unless you have explicitly specified NATIVE mode in your script. For example, if your script has not specified any mode, then it will change from using NATIVE mode to IFRAME sandbox mode. Please make sure that your UI works well in IFRAME sandbox mode.
On June 30th 2016, NATIVE mode will be shutdown. All scripts explicitly using NATIVE mode will default to IFRAME sandbox mode.
While deprecations may at times seem inconvenient, this staged deprecation should ease in the migration process. Our goal is to provide a modern and secure environment enabling developers to create great apps for their users with Google Apps Script.
Posted by Edward Jones, Software Engineer, Google Apps Script and Wesley Chun, Developer Advocate, Google Apps
Have you ever wanted a server API that modifies cells in a Google Sheet, to execute a Google Apps Script app from outside of Google Apps, or a way to use Apps Script as an API platform? Today, we’re excited to announce you can do all that and more with the Google Apps Script Execution API.
The Execution API allows developers to execute scripts from any client (browser, server, mobile, or any device). You provide the authorization, and the Execution API will run your script. If you’re new to Apps Script, it’s simply JavaScript code hosted in the cloud that can access authorized Google Apps data using the same technology that powers add-ons. The Execution API extends the ability to execute Apps Script code and unlocks the power of Docs, Sheets, Forms, and other supported services for developers.
One of our launch partners, Pear Deck, used the new API to create an interactive presentation tool that connects students to teachers by converting slide decks into interactive experiences. Their app calls the Execution API to automatically generate a Google Doc customized for each student, so everyone gets a personalized set of notes from the presentation. Without the use of Apps Script, their app would be limited to using PDFs and other static file types. Check out the video below to see how it works.
Bruce McPherson, a Google Developer Expert (GDE) for Google Apps, says: “The Execution API is a great tool for enabling what I call ‘incremental transition’ from Microsoft Office (and VBA) to Apps (and Apps Script). A mature Office workflow may involve a number of processes currently orchestrated by VBA, with data in various formats and locations. It can be a challenge to move an entire workload in one step, especially an automated process with many moving parts. This new capability enables the migration of data and process in manageable chunks.” You can find some of Bruce’s sample migration code using the Execution API here.
The Google Apps Script Execution API is live and ready for you to use today. To get started, check out the developer documentation and quickstarts. We invite you to show us what you build with the Execution API!
Editor's note: Posted by Romain Vialard, a Google Developer Expert and developer of Yet Another Mail Merge, a Google Sheets add-on.
Yet Another Mail Merge is a Google Sheets add-on that lets users send multiple personalized emails based on a template saved as a draft in Gmail and data in a Google Sheet. It can send hundreds of emails, but this kind of operation usually takes a few minutes to complete. This raises the question: what should be displayed in the user interface while a function is running on server side for a long time?
Firebase is all about real-time and became the answer to that issue. Last December, the Apps Script team announced a better version of the HtmlService with far fewer restrictions and the ability to use external JS libraries. With Firebase, we now had a solution to easily store and sync data in real-time.
Combined, users are able to know, in real-time, the number of emails sent by an Apps Script function running server-side. When the user starts the mail merge, it calls the Apps Script function that sends emails and connects to Firebase at the same time. Every time the Apps Script function has finished sending a new email, it increments a counter on Firebase and the UI is updated in real-time, as shown in the following image.
Inside the loop, each time an email is sent (i.e. each time we use the method GmailApp.sendEmail()), we use the Apps Script UrlFetch service to write into Firebase using its REST API. Firebase's capabilities makes this easy & secure and there’s no need for an OAuth Authorization Flow, just a Firebase app secret, as shown in the following example:
function addNewUserToFirebase() { var dbUrl = "https://test-apps-script.firebaseio.com"; var secret = PropertiesService.getScriptProperties().getProperty("fb-secret"); var path = "/users/"; var userData = { romainvialard:{ firstName:"Romain", lastName:"Vialard", registrationDate: new Date() } }; var params = { method: "PUT", payload : JSON.stringify(userData) } UrlFetchApp.fetch(dbUrl + path + ".json?auth=" + secret, params); }
On the client side, thanks to the improved Apps Script HtmlService, we can use the official JS client library to connect to Firebase and retrieve the data stored previously. Specifically, the on() method in this library can be used to listen for data changes at a particular location in our database. So each time a new task is completed on server side (e.g. new email sent), we notify Firebase and the UI is automatically updated accordingly.
var fb = new Firebase("https://test-apps-script.firebaseio.com"); var ref = fb.child('users/' + UID + '/nbOfEmailsSent'); ref.on("value", function(data) { if (data.val()) { document.getElementById("nbOfEmailsSent").innerHTML = data.val(); } });
In addition to the example above, there are other places where Firebase can be useful in Google Apps Script add-ons.
Those are just a few examples of what you can do with Apps Script and Firebase. Don’t hesitate to try it yourself or install Yet Another Mail Merge to see a live example. In addition, there is a public Apps Script library called FirebaseApp that can help you start with Firebase; use it like any other standard Apps Script library.
For example, you can easily fetch data from Firebase using specific query parameters:
function getFrenchContacts() { var firebaseUrl = "https://script-examples.firebaseio.com/"; var base = FirebaseApp.getDatabaseByUrl(firebaseUrl); var queryParameters = {orderBy:"country", equalTo: "France"}; var data = base.getData("", queryParameters); for(var i in data) { Logger.log(data[i].firstName + ' ' + data[i].lastName + ' - ' + data[i].country); } }
Build your own add-ons via Google Apps Script. Check out the documentation (developers.google.com/apps-script) to get more information as well as try out the Quickstart projects there. We look forward to seeing your add-ons soon!
Posted by Janet Traub, Program Manager, Google Apps APIs
The Google Apps Developer team recently hosted a 3-part Hangout On Air series that provided the developer community a unique opportunity to engage with the creative minds behind Google Apps developer tools. Each session covered topics ranging from business automation using Apps Script to Google Calendar API usage to creating Add-Ons for Docs & Sheets.
In the first installment of the series, Mike Harm, the creator of Apps Script and his colleague Kenzley Alphonse delivered a captivating session entitled, “Automate your Business with Apps Script.” Together, they reviewed the various features of Apps Script that can help developers build powerful solutions with Google Apps, such as simple scripts, to easily do a mail merge, export calendars into a Sheet, and to generate regularly scheduled reports.
The series then shifted focus to Google Calendar. In “Creating Calendar Events - Easy and Useful” Ali A. Rad (Product Manager) and Lucia Fedorova (Tech Lead) for Google Calendar API, explained how developers can benefit from injecting content into users’ calendars. In addition, they reviewed different approaches on Google Calendar to create events and meetings, such as API features, email markups, Android intents, Calendar import, and more.
We concluded the series with “How to Increase Traffic to Your Add-On with Google Apps Script.” This session, delivered by Apps Script Product Manager, Saurabh Gupta and Mike Harm, gave developers an in depth understanding of the Add-Ons framework, steps to deployment and strategies to increase adoption of their Docs, Sheets and Forms Add-Ons.
For more information on developing for Google Apps, visit developers.google.com/google-apps
Posted by Saurabh Gupta, Product Manager
Originally posted to Google Developers blog
Back in 2014, we introduced add-ons for Google Docs, Sheets, and Forms in developer preview. Since then, the developer community has built a wide variety of features to help millions of Docs, Sheets and Forms users become more productive. Over the last few months, we launched a number of developer-friendly features that made it easier to build, test, deploy and distribute add-ons. Some key capabilities include:
With these features under our belt, we are ready to graduate add-ons out of developer preview. Starting today, any developer can publish an add-on. To ensure users find the best tools for them, every new add-on will undergo a review for adherence to our guidelines before it’s available in the add-ons store.
We can’t wait to see what you will build!
Posted by Kalyan Reddy, Developer Programs Engineer
Apps Script includes many built-in Google services for major products like Gmail and Drive, and lately, we've been working to add other APIs that developers have been clamoring for as advanced Google services. Today, we are launching seven more advanced services, including:
Like all other advanced services in Apps Script, they must first be enabled before use. Once enabled, they are just as easy to use as built-in Apps Script services -- the editor provides autocomplete, and the authentication flow is handled automatically.
Here is a sample using the Apps Activity advanced service that shows how to get a list of users that have performed an action on a particular Google Drive file.
function getUsersActivity() { var fileId = 'YOUR_FILE_ID_HERE'; var pageToken; var users = {}; do { var result = AppsActivity.Activities.list({ 'drive.fileId': fileId, 'source': 'drive.google.com', 'pageToken': pageToken }); var activities = result.activities; for (var i = 0; i < activities.length; i++) { var events = activities[i].singleEvents; for (var j = 0; j < events.length; j++) { var event = events[j]; users[event.user.name] = true; } } pageToken = result.nextPageToken; } while (pageToken); Logger.log(Object.keys(users)); }
This function uses the AppsActivity.Activities.list() method, passing in the required parameters drive.fileId and source, and uses page tokens to get the full list of activities. The full list of parameters this method accepts can be found in the Apps Activity API's reference documentation.
AppsActivity.Activities.list()
drive.fileId
source
Update (2015-06-15): The sunset date listed below has been changed from June 26th to July 6th, 2015.
Posted by Eric Koleda, Developer Platform Engineer
OAuth is the de facto standard for authorization today and is used by most modern APIs. Apps Script handles the OAuth flow automatically for dozens of built-in and advanced services, but until recently only had limited support for connecting to other OAuth-protected APIs such as Twitter, etc. The URL Fetch service’s OAuthConfig class only works with the older OAuth 1.0 standard and only allows the developer of the script (not its users) to grant access to their data. To address this, we’ve create two new open source libraries:
OAuthConfig
With only a few clicks, you can add these libraries to your scripts. The full source code is available on GitHub if you need to tinker with how they work. These libraries allow for greater control over the OAuth flow, including the ability for users to grant access separately, a long standing feature request from the community.
We believe that these open libraries are a better alternative to our previous solution, and therefore we are deprecating the OAuthConfig class. The class will continue to function until July 6, 2015, after which it will be removed completely and any scripts that use it will stop working We’ve prepared a migration guide that walks you through the process of upgrading your existing scripts to use these new libraries.
Separate from these changes in Apps Script and as announced in 2012, all Google APIs will stop supporting OAuth 1.0 for inbound requests on April 20, 2015. If you use OAuthConfig to connect to Google APIs, you will need to migrate before that date. Update your code to use the OAuth2 library or the API’s equivalent Advanced Service if one exists.
We see Apps Script and Sheets as the perfect hub for connecting together data inside and outside of Google, and hope this additional OAuth functionality makes it an even more compelling platform.
DocsListDialog is a widget used by only a small fraction of Apps Script projects to provide a Google Drive "file open" dialog in a UI service user interface. In almost all cases, using Google Picker in HTML service is preferable and more secure.
DocsListDialog
Before September 30, 2014, we require scripts using DocsListDialog to make a small update to improve security.
Specifically, if you use DocsListDialog, you'll need to start calling a new method, setOAuthToken(oAuthToken) before you call showDocsPicker(). The new method sets an OAuth 2.0 token to use when fetching data for the dialog, on behalf of the user whose content should be shown.
setOAuthToken(oAuthToken)
showDocsPicker()
So long as the app isn't a web app set to execute as "me" (the developer), you can get the necessary OAuth 2.0 token by calling ScriptApp.getOAuthToken(). The example below shows how to convert an old DocsListDialog implementation to the new model.
ScriptApp.getOAuthToken()
function showDialog() { var app = UiApp.createApplication(); app.createDocsListDialog() .addCloseHandler(serverHandler) .addSelectionHandler(serverHandler) .showDocsPicker(); SpreadsheetApp.getUi() .showModalDialog(app,' '); }
function showDialog() { var app = UiApp.createApplication(); app.createDocsListDialog() .addCloseHandler(serverHandler) .addSelectionHandler(serverHandler) .setOAuthToken(ScriptApp.getOAuthToken()) .showDocsPicker(); SpreadsheetApp.getUi() .showModalDialog(app,' '); }
To ensure your script continues to work properly, be sure to make this change before September 30.
Posted by Dan Lazin, Googler
Editor’s Note: Guest author Alex Moore is the CEO of Baydin, an email productivity company. --Arun Nagarajan
var d = new Date(); d.setDate(d.getDate() - DAYS_TO_SEARCH); var dateString = d.getFullYe ar() + "/" + (d.getMonth() + 1) + "/" + d.getDate(); threads = GmailApp.search("in:Sent after:" + dateString);
var userEmailAddress = Session.getEffectiveUser().getEmail(); var EMAIL_REGEX = /[a-zA-Z0-9\._\-]+@[a-zA-Z0-9\.\-]+\.[a-z\.A-Z]+/g; # if the label already exists, createLabel will return the existing label var label = GmailApp.createLabel("AwaitingResponse"); var threadsToUpdate = []; for (var i = 0; i < threads.length; i++) { var thread = threads[i]; var lastMessage = thread.getMessages()[thread.getMessageCount()-1]; lastMessageSender = lastMessage.getFrom().match(EMAIL_REGEX)[0]; if (lastMessageSender == userEmailAddress) { threadsToUpdate.push[thread]; } } label.addToThreads(threads)
