Security News
The Unpaid Backbone of Open Source: Solo Maintainers Face Increasing Security Demands
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
@backstage/plugin-analytics-module-ga
Advanced tools
This plugin provides an opinionated implementation of the Backstage Analytics API for Google Analytics. Once installed and configured, analytics events will be sent to GA as your users navigate and use your Backstage instance.
This plugin contains no other functionality.
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-analytics-module-ga
// packages/app/src/apis.ts
import {
analyticsApiRef,
configApiRef,
identityApiRef,
} from '@backstage/core-plugin-api';
import { GoogleAnalytics } from '@backstage/plugin-analytics-module-ga';
export const apis: AnyApiFactory[] = [
// Instantiate and register the GA Analytics API Implementation.
createApiFactory({
api: analyticsApiRef,
deps: { configApi: configApiRef, identityApi: identityApiRef },
factory: ({ configApi, identityApi }) =>
GoogleAnalytics.fromConfig(configApi, {
identityApi,
}),
}),
];
app-config.yaml
:The following is the minimum configuration required to start sending analytics events to GA. All that's needed is your Universal Analytics tracking ID:
# app-config.yaml
app:
analytics:
ga:
trackingId: UA-0000000-0
app-config.yaml
:The following is the minimal content security policy required to load scripts from GA.
backend:
csp:
connect-src: ["'self'", 'http:', 'https:']
# Add these two lines below
script-src: ["'self'", "'unsafe-eval'", 'https://www.google-analytics.com']
img-src: ["'self'", 'data:', 'https://www.google-analytics.com']
In order to be able to analyze usage of your Backstage instance by plugin, we strongly recommend configuring at least one custom dimension to capture Plugin IDs associated with events, including page views.
hit
, and name it something like Plugin
. Note
the index of the dimension you just created (e.g. 1
, if this is the first
custom dimension you've created in your GA property).app.analytics.ga
configuration that instructs
the plugin to capture Plugin IDs on the custom dimension you just created.
It should look like this:app:
analytics:
ga:
trackingId: UA-0000000-0
customDimensionsMetrics:
- type: dimension
index: 1
source: context
key: pluginId
You can configure additional custom dimension and metric collection by adding
more entries to the customDimensionsMetrics
array:
app:
analytics:
ga:
customDimensionsMetrics:
- type: dimension
index: 1
source: context
key: pluginId
- type: dimension
index: 2
source: context
key: routeRef
- type: dimension
index: 3
source: context
key: extension
- type: metric
index: 1
source: attributes
key: someEventContextAttr
This plugin supports accurately deriving user-oriented metrics (like monthly active users) using Google Analytics' user ID views. To enable this...
Be sure you've gone through the process of setting up a user ID view in your Backstage instance's Google Analytics property (see docs linked above).
Make sure you instantiate GoogleAnalytics
with an identityApi
instance
passed to it, as shown in the installation section above.
Set app.analytics.ga.identity
to either required
or optional
in your
app.config.yaml
, like this:
app:
analytics:
ga:
trackingId: UA-0000000-0
identity: optional
Set identity
to optional
if you need accurate session counts, including
cases where users do not sign in at all. Use required
if you need all hits
to be associated with a user ID without exception (and don't mind if some
sessions are not captured, such as those where no sign in occur).
Note that, to comply with GA policies, the value of the User ID is
pseudonymized before being sent to GA. By default, it is a sha256
hash of the
current user's userEntityRef
as returned by the identityApi
. To set a
different value, provide a userIdTransform
function alongside identityApi
when you instantiate GoogleAnalytics
. This function will be passed the
userEntityRef
as an argument and should resolve to the value you wish to set
as the user ID. For example:
import {
analyticsApiRef,
configApiRef,
identityApiRef,
} from '@backstage/core-plugin-api';
import { GoogleAnalytics } from '@backstage/plugin-analytics-module-ga';
export const apis: AnyApiFactory[] = [
createApiFactory({
api: analyticsApiRef,
deps: { configApi: configApiRef, identityApi: identityApiRef },
factory: ({ configApi, identityApi }) =>
GoogleAnalytics.fromConfig(configApi, {
identityApi,
userIdTransform: async (userEntityRef: string): Promise<string> => {
return customHashingFunction(userEntityRef);
},
}),
}),
];
If you wish to see all of the search events in the Site Search
section of Google Analytics, you can enable sending virtual pageviews on every search
event like so:
app:
analytics:
ga:
virtualSearchPageView:
mode: only # Defaults to 'disabled'
mountPath: /virtual-search # Defaults to '/search'
searchQuery: term # Defaults to 'query'
categoryQuery: sc # Omitted by default
Available mode
s are:
disabled
- no virtual pageviews are sent, default behavioronly
- sends virtual pageviews instead of search
eventsboth
- sends both virtual pageviews and search
eventsVirtual pageviews will be sent to the path specified in the mountPath
, the search term will be
set as the value for query parameter searchQuery
and category (if provided) will be set as the value for
query parameter categoryQuery
, e.g. the example config above will result in
virtual pageviews being sent to /virtual-search?term=SearchTermHere&sc=CategoryHere
.
In pre-production environments, you may wish to set additional configurations to turn off reporting to Analytics and/or print debug statements to the console. You can do so like this:
app:
analytics:
ga:
testMode: true # Prevents data being sent to GA
debug: true # Logs analytics event to the web console
You might commonly set the above in an app-config.local.yaml
file, which is
normally gitignore
'd but loaded and merged in when Backstage is bootstrapped.
If you would like to contribute improvements to this plugin, the easiest way to make and test changes is to do the following:
git clone git@github.com:backstage/backstage.git
yarn install
app-config.local.yaml
file in the root of
the monorepo and add config for this plugin (see below)cd plugins/analytics-provider-ga
yarn start
http://localhost:3000/ga
Code for the isolated version of the plugin can be found inside the /dev directory. Changes to the plugin are hot-reloaded.
Paste this into your app-config.local.yaml
while developing this plugin:
app:
analytics:
ga:
trackingId: UA-0000000-0
debug: true
testMode: true
customDimensionsMetrics:
- type: dimension
index: 1
source: context
key: pluginId
FAQs
Unknown package
We found that @backstage/plugin-analytics-module-ga demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.
Security News
A developer is accusing Tencent of violating the GPL by modifying a Python utility and changing its license to BSD, highlighting the importance of copyleft compliance.