Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/romainvialard/analyticsmp
Make calls to the Google Analytics Measurement Protocol from Google Apps Script
https://github.com/romainvialard/analyticsmp
apps-script google-analytics google-apps-script
Last synced: 2 months ago
JSON representation
Make calls to the Google Analytics Measurement Protocol from Google Apps Script
- Host: GitHub
- URL: https://github.com/romainvialard/analyticsmp
- Owner: RomainVialard
- Created: 2018-05-29T08:45:42.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-10-06T07:34:02.000Z (over 4 years ago)
- Last Synced: 2024-11-16T09:19:34.692Z (2 months ago)
- Topics: apps-script, google-analytics, google-apps-script
- Language: JavaScript
- Homepage:
- Size: 10.7 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# AnalyticsMP
This is a library for **Google Apps Script** projects. It provides methods to send data to Google Analytics from server side via the [Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/v1/) (hence the name 'AnalyticsMP').
On client side, a [client ID](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#clientId) is stored in the browsers cookies, "_so subsequent visits to the same site can be associated with the same user_". Here a server-side client ID is automatically generated and saved among the [User Properties](https://developers.google.com/apps-script/guides/properties) of your project. If you want to use Google Analytics both on server side and client side (from the HTML Service), it is advised to retrieve the client ID generated on server side (via the method getAnalyticsClientId() of this library) and reuse it on the client side so that all calls are performed with the same client ID for a given user.
For more information read this blog post:
[Google Apps Script: Tracking add-on usage with Google Analytics](https://cloud.google.com/blog/products/application-development/google-apps-script-tracking-add-on).
# Methods
## sendAnalyticsEvent(parameters, optPropertyStore)
Use this method to send events (default) or pageviews to Google Analytics. The list of all possible parameters is available here:
[https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters)
### Example
```JS
// The tracking ID / web property ID can be set as a global variable named ANALYTICS_TRACKING_ID or can be added in each call via the 'tid' parameter.
var ANALYTICS_TRACKING_ID = 'UA-17845631-4';
AnalyticsMP.sendAnalyticsEvent({
'ec': 'Add-on installed',
'ea': Session.getActiveUserLocale()
});
```
### Parameters
Name
Type
Description
parameters
Object
Parameters for the Measurement Protocol, full list documented here
optPropertyStore
Properties
Optional - useful to avoid making too many calls to PropertiesService.getUserProperties() or simply to switch to another property store (Document / Script)
## getAnalyticsClientId(optPropertyStore)
Generate a unique user ID if none was previously stored in a PropertyService or return the existing stored UUID.
On server side, the client ID should always be the same for a given user. On client side it is usually stored as a cookie (and thus is usually browser / device related instead of user related).
Here it makes sense to save it as a User Property. This method can also be called from client side to use the same client ID on both server & client (useful for [session aggregation](https://support.google.com/analytics/answer/2731565?hl=en)).
### Parameters
Name
Type
Description
optPropertyStore
Properties
Optional - useful to avoid making too many calls to PropertiesService.getUserProperties() or simply to switch to another property store (Document / Script)
## generateAnalyticsTrackingUrl(parameters, optPropertyStore)
Build a tracking url, useful eg: to place a tracking beacon in emails sent:
https://developers.google.com/analytics/devguides/collection/protocol/v1/email
### Parameters
Name
Type
Description
parameters
Object
Parameters for the Measurement Protocol, full list documented here
optPropertyStore
Properties
Optional - useful to avoid making too many calls to PropertiesService.getUserProperties() or simply to switch to another property store (Document / Script)
# Setup
You can copy the code of this library in your own Google Apps Script project or reuse it as a [standard library](https://developers.google.com/apps-script/guides/libraries). In both cases, methods are called using the AnalyticsMP class / namespace, meaning you will use them exactly in the same way.
To install it as a library, use the following script ID and select the latest version:
`1Bw6UvY6EUalhtNbuwF6TyemIUHCxPZg-HoSHlUfbVbwYqvY9ZKu0mNMO`
To copy the code in your project, simply copy-past the content of this file in a new script file in your project:
[https://github.com/RomainVialard/AnalyticsMP/blob/master/src/AnalyticsMP.js](https://github.com/RomainVialard/AnalyticsMP/blob/master/src/AnalyticsMP.js)
It is recommended - but not mandatory - to also include in your project the [ErrorHandler](https://github.com/RomainVialard/ErrorHandler) library. If installed, it will automatically be used by AnalyticsMP methods to perform an Exponential backoff logic whenever it is needed.
# Warning
This library contains 3 methods directly available as functions and callable without using the AnalyticsMP class / namespace:
* sendAnalyticsEvent()
* getAnalyticsClientId()
* generateAnalyticsTrackingUrl()
For this reason, if you copy the code in your project, make sure you don't have any other function with the exact same name.