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.
The APIs for three of Apps Script's advanced services — Analytics, BigQuery, and Prediction — will undergo breaking changes on Monday, November 18. If you don't update your code to the new syntax before then, you'll receive error messages such as Required parameter is missing.
Required parameter is missing
Advanced services allow you to easily connect to certain public Google APIs from Apps Script. We're working to expand and improve our advanced services, and as a side effect some methods and parameters that were incorrectly listed as optional are now required.
On November 18, these services will switch to use the new method signatures shown in the tables below. To learn how new arguments should be structured, refer to the documentation for the underlying API. For example, the documentation for the BigQuery service's Jobs.query() method shows the valid properties for the resource object in the "Request body" section of the page.
Jobs.query()
resource
Analytics.Management.Uploads
.deleteUploadData( accountId, webPropertyId, customDataSourceId, optionalArgs)
.deleteUploadData( resource, accountId, webPropertyId, customDataSourceId)
BigQuery.Datasets
.insert( resource, optionalArgs)
.insert( resource, projectId)
.update( resource, optionalArgs)
.update( resource, projectId, datasetId)
BigQuery.Jobs
.insert( resource, mediaData, optionalArgs)
.insert( resource, projectId, mediaData)
.query( projectId, query)
.query( resource, projectId)
BigQuery.Tabledata
.insertAll( projectId, datasetId, tableId, optionalArgs)
.insertAll( resource, projectId, datasetId, tableId)
BigQuery.Tables
.insert( resource, projectId, datasetId)
.update( resource, projectId, datasetId, tableId)
Prediction.Hostedmodels
.predict( project, hostedModelName, optionalArgs)
.predict( resource, project, hostedModelName)
Prediction.Trainedmodels
.insert( project, optionalArgs)
.insert( resource, project)
.predict( project, id, optionalArgs)
.predict( resource, project, id)
.update( project, id, optionalArgs)
.update( resource, project, id)
If you want to prepare your code ahead of time, you can add a try/catch around your existing code that retries with the new method signature if the old one fails. For example, the following sample applies this approach to the BigQuery service's Jobs.query() method:
try/catch
var result; try { result = BigQuery.Jobs.query(projectId, query, { timeoutMs: 10000 }); } catch (e) { // Refer to the BigQuery documentation for the structure of the // resource object. var resource = { query: query, timeoutMs: 1000 }; result = BigQuery.Jobs.query(resource, projectId); }
We apologize for inconvenience and look forward to sharing exciting news about advanced services in the coming weeks.
Editor's note: This has been cross-posted with the Google Analytics blog and the Google Developers blog -- Jan Kleinert
Many people have been asking for a simple way to put Google Analytics data into a Google Spreadsheet. Once the data is inside a Google Spreadsheet, users can easily manipulate Google Analytics data, create new visualizations, and build internal dashboards.
So today we released a new integration that dramatically reduces the work required to put Google Analytics data into any Apps Script supported product, such as Google Docs, Sites, or Spreadsheets.
Here’s an example of Google Analytics data accessed through Apps Script and displayed in a Google Spreadsheet.
We know that a popular use case of this integration will be to create dashboards that automatically update. To make this easy to do, we’ve added a script to the Spreadsheets script gallery that handles all this work - no code required. The script is called Google Analytics Report Automation (Magic).
This script is a great template for starting your own project, and we’ve had many internal Google teams save hours of time using this tool. Here’s a video demoing how to build a dashboard using this script:
You can find this script by opening or creating a Google Spreadsheet, clicking Tools -> Script Gallery and searching for “analytics magic”.
Of course many developers will want to write their own code. With the new Analytics – Apps Script integration, you can request the total visitors, visits, and pageviews over time and put this data into a spreadsheet with just the following code:
// Get Data. var results = Analytics.Data.Ga.get( tableId, startDate, endDate, 'ga:visitors,ga:visits,ga:pageviews', {‘dimensions’: ‘ga:date’}); // Output to spreadsheet. var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet(); sheet.getRange(2, 1, results.getRows().length, headerNames.length) .setValues(results.getRows()); // Make Sandwich.
To get started now, read our Automated Access to Google Analytics Data in Google Spreadsheets tutorial. Also check out the Google Analytics Apps Script reference docs.
Are you ready to start building solutions using Google Analytics and Google Apps Script?
We’d love to hear new ways you use this integration to help manipulate, visualize and present data to solve business problems. To encourage you to try out this integration, we are giving out Google Analytics developer t-shirts to the first 15 developers to build a solution using both APIs.
To be eligible, you must publish your solution to either the Chrome Web Store or the Spreadsheets Script Gallery and include a description of a business problem the script solves. We’ll then collect these scripts and highlight the solutions in an upcoming blog post. After you publish your script, fill out this form to share what you’ve built.
We’re looking forward to seeing what you can do with this integration.
