ember-google-analytics-embed
v0.3.1
Published
An Ember.js Addon for adding analytics visualizations using the Google Analytics Embed API.
Downloads
26
Maintainers
Readme
Ember Google Analytics Embed
Ember Google Analytics Embed is an addon for quickly building custom Google Analytics dashboards in your Ember.js app, using the Google Analytics Embed API.
The addon exposes the following components to use in your templates:
- Bar Chart (ga-embed-bar-chart)
- Column Chart (ga-embed-column-chart)
- Geo Chart (ga-embed-geo-chart)
- Line Chart (ga-embed-line-chart)
- Pie Chart (ga-embed-pie-chart)
- Table (ga-embed-table)
The addon also enables Analytics user authorization using the authorization (ga-embed-authorize) component and view selection via the view selector (ga-embed-view-selector) component.
Demos
Check out the Embed API demos page for examples.
Installation
ember install ember-google-analytics-embed
Setup
To authorize your application to access the Google Analytics API, you must create a Client ID from the Google API Console. When you've obtained your Client ID, add it to your environment file. If you are using Geo Charts, you must also include an API Key, for accessing the Google Maps Javascript API. Both these APIs must be enabled from your API console and have the right origins/referrers set.
// config/environment.js
ENV['google-analytics-embed'] = {
clientId: 'YOUR_CLIENT_ID',
apiKey: 'YOUR_API_KEY'
};
Authorization
There are two ways to authorize users: through the authorization flow, requiring a user to click and authenticate, or via an access token sent from your server.
Adding the base ga-embed-authorize
component to your templates will create a 'Sign in to Google Analytics' button and handle the authorization flow automatically:
{{ga-embed-authorize}}
Inject the ga-embed
service into your templates to conditionally show/hide elements:
{{#if gaEmbed.isAuthorized}}
// Add visualizations here
{{/if}}
The ga-embed
service also exposes information about the current authorized user:
{{log gaEmbed.authorizedUser}}
// => { email: '[email protected]', imageUrl: '...', name: 'Foo Bar' }
Sign Out
To enable the user to sign out, inject the ga-embed
service into the consuming object and create the following action.
gaEmbed: service(),
actions: {
signOut() {
get(this, 'gaEmbed').signOut().then(() => {
// Returns a promise when complete
});
}
}
Access Token Authorization
To remove the user auth flow, you may return an access token from your server. Simply pass the access token to the ga-embed-authorize
component. You can find more information on setting up server side authorization here.
{{ga-embed-authorize accessToken=analyticsAccessToken}}
Visualizations
Each visualization accepts two main attributes, a query and an options hash.
Query
To get data from our Google Analytics property, we must build a query using the Google Reporting API. The example below shows a pie chart of sessions, segmented by country. It limits the data to the last 30 days up until today and requests just the top ten results.
{{ga-embed-pie-chart
query=(hash
ids="YOUR_PROPERTY_ID"
metrics="ga:sessions"
dimensions="ga:country"
start-date="30daysAgo"
sort="-ga:sessions"
max-results=10
end-date="today"
)}}
Options
An options hash may be passed to each chart, allowing full configuration of the visualization.
{{ga-embed-pie-chart query=query options=options}}
Individual options properties may also be passed and can be dynamically updated.
{{ga-embed-pie-chart
query=query
options=options
title="Sessions by country"
is3D=pieChartIs3D
}}
Components
Bar Chart
Creates a bar chart visualization and accepts the following configuration options.
{{ga-embed-bar-chart query=query options=options}}
Column Chart
Creates a column chart visualization and accepts the following configuration options.
{{ga-embed-column-chart query=query options=options}}
Geo Chart
Creates a geo chart visualization and accepts the following configuration options. This component lazy-loads the Google Maps Geocoding API.
The region property can be dynamically updated and is validated before the chart is updated to ensure a valid region code is used.
{{ga-embed-geo-chart query=query options=options region=region}}
Line Chart
Creates a line chart visualization and accepts the following configuration options.
{{ga-embed-line-chart query=query options=options}}
Pie Chart
Creates a pie chart visualization and accepts the following configuration options.
To transform a pie chart into a donut chart, simply add a value for the pie hole.
{{ga-embed-pie-chart query=query options=options pieHole=0.4}}
Table
Creates a table visualization and accepts the following configuration options.
{{ga-embed-table query=query options=options}}
Loading State
Each visualization has a loading state class of .ga-embed-visualization-loading
, which you can customize in your CSS. The classes set on visualizations allow for custom loading states per visualization.
<div id="ember123" class="ga-embed-visualization ga-embed-chart ga-embed-line-chart ga-embed-visualization-loading">...</div>
Auto Resizing
By default, visualizations auto resize on window resize. To disable auto resizing, set responsiveResize=false
on the visualization.
{{ga-embed-line-chart query=query options=options responsiveResize=false}}
Debouncing
When dynamically updating many properties on a visualization, it may be beneficial to debounce executing a new render. To do so, the visualization accepts a debounce
value in milliseconds (ms).
{{ga-embed-line-chart query=query options=options debounce=100}}
View Selection
The ga-embed-view-selector
component allows the user to select a view from any property they are authorized on. Add the view selector component to your template.
{{#if gaEmbed.isAuthorized}}
{{ga-embed-view-selector ids=(mut viewIds) onChange=(action 'customAction')}}
{{/if}}
Use the mutable property in your queries:
{{ga-embed-pie-chart
query=(hash
ids=viewIds
// ...
)}}
Querying the Reporting API
The gaEmbed
service enables a quick method to query data from analytics without directly using a visualization. This can be useful for querying the Google Analytics Reporting API and using the data in your own custom components.
get(this, 'gaEmbed').getData({
'ids': 'YOUR_PROPERTY_ID',
'metrics': 'ga:sessions',
'dimensions': 'ga:date',
'start-date': '30daysAgo',
'end-date': 'yesterday'
}).then(data => {
console.log(data);
}).catch(err => {
console.log(err);
});
Using Google Analytics Embed API
Contributing
A crude dummy app demonstrates all the functionality of the addon. To view the dummy app, clone the repo and simply create a .env file with the following information:
# .env
GOOGLE_API_KEY=YOUR_API_KEY
GOOGLE_CLIENT_ID=YOUR_CLIENT_ID
Then start the server using:
ember serve