paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 25 Packages Projects Releases Wiki Activity

Deprecate packages

Browse Source 
Signed-off-by: blam <ben@blam.sh>
This commit is contained in:
blam
2024-04-18 20:44:21 +02:00
parent 112b4647c4
commit 0360e89418
7 changed files with 25 additions and 630 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/migrate-1713465859342.md
+7
View File
@@ -0,0 +1,7 @@
---
'@backstage/plugin-analytics-module-ga': patch
'@backstage/plugin-analytics-module-ga4': patch
'@backstage/plugin-analytics-module-newrelic-browser': patch
---
These packages have been migrated to the [backstage/community-plugins](https://github.com/backstage/community-plugins) repository.
plugins/analytics-module-ga/README.md
+2 -258
View File
@@ -1,259 +1,3 @@
# Analytics Module: Google Analytics
# Deprecated
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.
## Installation
1. Install the plugin package in your Backstage app:
```sh
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-analytics-module-ga
```
2. Wire up the API implementation to your App:
```tsx
// 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,
}),
}),
];
```
3. Configure the plugin in your `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:
```yaml
# app-config.yaml
app:
analytics:
ga:
trackingId: UA-0000000-0
```
4. Update CSP in your `app-config.yaml`:
The following is the minimal content security policy required to load scripts from GA.
```yaml
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']
```
## Configuration
In order to be able to analyze usage of your Backstage instance _by plugin_, we
strongly recommend configuring at least one [custom dimension][what-is-a-custom-dimension]
to capture Plugin IDs associated with events, including page views.
1. First, [configure the custom dimension in GA][configure-custom-dimension].
Be sure to set the Scope to `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).
2. Then, add a mapping to your `app.analytics.ga` configuration that instructs
the plugin to capture Plugin IDs on the custom dimension you just created.
It should look like this:
```yaml
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:
```yaml
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
```
### User IDs
This plugin supports accurately deriving user-oriented metrics (like monthly
active users) using Google Analytics' [user ID views][ga-user-id-view]. To
enable this...
1. 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).
2. Make sure you instantiate `GoogleAnalytics` with an `identityApi` instance
passed to it, as shown in the installation section above.
3. Set `app.analytics.ga.identity` to either `required` or `optional` in your
`app.config.yaml`, like this:
```yaml
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:
```typescript
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);
},
}),
}),
];
```
### Enabling Site Search
If you wish to see all of the search events in the [Site Search](https://support.google.com/analytics/answer/1012264)
section of Google Analytics, you can enable sending virtual pageviews on every `search` event like so:
```yaml
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 behavior
- `only` - sends virtual pageviews _instead_ of `search` events
- `both` - sends both virtual pageviews _and_ `search` events
Virtual 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`.
### Debugging and Testing
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:
```yaml
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.
## Development
If you would like to contribute improvements to this plugin, the easiest way to
make and test changes is to do the following:
1. Clone the main Backstage monorepo `git clone git@github.com:backstage/backstage.git`
2. Install all dependencies `yarn install`
3. If one does not exist, create an `app-config.local.yaml` file in the root of
the monorepo and add config for this plugin (see below)
4. Enter this plugin's working directory: `cd plugins/analytics-provider-ga`
5. Start the plugin in isolation: `yarn start`
6. Navigate to the playground page at `http://localhost:3000/ga`
7. Open the web console to see events fire when you navigate or when you
interact with instrumented components.
Code for the isolated version of the plugin can be found inside the [/dev](./dev)
directory. Changes to the plugin are hot-reloaded.
### Recommended Dev Config
Paste this into your `app-config.local.yaml` while developing this plugin:
```yaml
app:
analytics:
ga:
trackingId: UA-0000000-0
debug: true
testMode: true
customDimensionsMetrics:
- type: dimension
index: 1
source: context
key: pluginId
```
[what-is-a-custom-dimension]: https://support.google.com/analytics/answer/2709828
[configure-custom-dimension]: https://support.google.com/analytics/answer/2709828#configuration
[ga-user-id-view]: https://support.google.com/analytics/answer/3123669
This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-analytics-module-ga` instead.
plugins/analytics-module-ga/package.json
+4 -2
View File
@@ -2,7 +2,8 @@
"name": "@backstage/plugin-analytics-module-ga",
"version": "0.2.4",
"backstage": {
"role": "frontend-plugin-module"
"role": "frontend-plugin-module",
"moved": "@backstage-community/plugin-analytics-module-ga"
},
"publishConfig": {
"access": "public",
@@ -52,5 +53,6 @@
"react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
"react-router-dom": "6.0.0-beta.0 || ^6.3.0"
},
"configSchema": "config.d.ts"
"configSchema": "config.d.ts",
"deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-analytics-module-ga instead."
}
plugins/analytics-module-ga4/README.md
+2 -232
View File
@@ -1,233 +1,3 @@
# Analytics Module: Google Analytics 4
# Deprecated
This plugin provides an opinionated implementation of the Backstage Analytics
API for Google Analytics 4. 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.
## Installation
1. Install the plugin package in your Backstage app:
```sh
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-analytics-module-ga4
```
2. Wire up the API implementation to your App:
```tsx
// packages/app/src/apis.ts
import {
analyticsApiRef,
configApiRef,
identityApiRef,
} from '@backstage/core-plugin-api';
import { GoogleAnalytics4 } from '@backstage/plugin-analytics-module-ga4';
export const apis: AnyApiFactory[] = [
// Instantiate and register the GA Analytics API Implementation.
createApiFactory({
api: analyticsApiRef,
deps: { configApi: configApiRef, identityApi: identityApiRef },
factory: ({ configApi, identityApi }) =>
GoogleAnalytics4.fromConfig(configApi, {
identityApi,
}),
}),
];
```
3. Configure the plugin in your `app-config.yaml`:
The following is the minimum configuration required to start sending analytics
events to GA. All that's needed is your GA4 measurement ID:
```yaml
# app-config.yaml
app:
analytics:
ga4:
measurementId: G-0000000-0
```
4. Update CSP in your `app-config.yaml`:
The following is the minimal content security policy required to load scripts from GA.
```yaml
backend:
csp:
connect-src: ["'self'", 'http:', 'https:']
# Add these two lines below
script-src:
[
"'self'",
"'unsafe-eval'",
'https://www.google-analytics.com',
'https://www.googletagmanager.com',
]
img-src: ["'self'", 'data:', 'https://www.google-analytics.com']
```
## Configuration
In order to be able to analyze usage of your Backstage instance by plugin, we recommend configuring [a content grouping](#enabling-content-grouping).
Additional dimensional data can be captured using custom dimensions, like this:
1. First, [configure the custom dimension in GA] [configure-custom-dimension].
Be sure to set the Scope to `Event`, and name it `dimension1`.
2. Then, add a mapping to your `app.analytics.ga4` configuration that instructs
the plugin to capture Plugin IDs on the custom dimension you just created.
It should look like this:
3. `allowedContexts` config accepts array of string, where each entry is a context parameter that will be sent in the event.
context names will be prefixed by `c_`.
4. `allowedAttributes` config accepts array of string, where each entry is an attribute that will be sent in the event.
attribute names will be prefixed by `a_`.
5. `allowedContexts` and `allowedAttributes` are optional, if not provided, no additional context and attributes will be sent.
6. if `allowedContexts` or `allowedAttributes` is set to '\*', all context and attributes will be sent.
7. `enableSendPageView` is used to send default events and is disabled by default.
```yaml
app:
analytics:
ga4:
measurementId: G-0000000-0
allowedContexts: ['pluginId']
```
```yaml
app:
analytics:
ga4:
allowedContexts: ['pluginId']
allowedAttributes: ['someEventContextAttr']
```
### User IDs
This plugin supports accurately deriving user-oriented metrics (like monthly
active users) using Google Analytics' [user ID views][ga-user-id-view]. To
enable this...
1. 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).
2. Make sure you instantiate `GoogleAnalytics` with an `identityApi` instance
passed to it, as shown in the installation section above.
3. Set `app.analytics.ga4.identity` to either `required` or `optional` in your
`app.config.yaml`, like this:
```yaml
app:
analytics:
ga4:
measurementId: G-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:
```typescript
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 }) =>
GoogleAnalytics4.fromConfig(configApi, {
identityApi,
userIdTransform: async (userEntityRef: string): Promise<string> => {
return customHashingFunction(userEntityRef);
},
}),
}),
];
```
### Enabling content grouping
Content groups enable you to categorize pages and screens into custom buckets which you can see
metrics for related groups of information.
More about content grouping here [content groups][content-grouping].
It's recommended to enable content grouping by PluginId. `contentGrouping` supports `routeRef` and extension.
```yaml
app:
analytics:
ga4:
contentGrouping: pluginId
```
Please note, content grouping takes 24hrs to show up in the Google Analytics dashboard.
### Debugging and Testing
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:
```yaml
app:
analytics:
ga4:
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.
## Development
If you would like to contribute improvements to this plugin, the easiest way to
make and test changes is to do the following:
1. Clone the main Backstage monorepo `git clone git@github.com:backstage/backstage.git`
2. Install all dependencies `yarn install`
3. If one does not exist, create an `app-config.local.yaml` file in the root of
the monorepo and add config for this plugin (see below)
4. Enter this plugin's working directory: `cd plugins/analytics-provider-ga4`
5. Start the plugin in isolation: `yarn start`
6. Navigate to the playground page at `http://localhost:3000/ga4`
7. Open the web console to see events fire when you navigate or when you
interact with instrumented components.
Code for the isolated version of the plugin can be found inside the [/dev](./dev)
directory. Changes to the plugin are hot-reloaded.
#### Recommended Dev Config
Paste this into your `app-config.local.yaml` while developing this plugin:
```yaml
app:
analytics:
ga4:
measurementId: G-0000000-0
debug: true
testMode: true
allowedContexts: ['pluginId']
```
[what-is-a-custom-dimension]: https://support.google.com/analytics/answer/2709828
[configure-custom-dimension]: https://support.google.com/analytics/answer/10075209?hl=en#
[ga-user-id-view]: https://support.google.com/analytics/answer/3123669
[content-grouping]: https://support.google.com/analytics/answer/11523339?hl=en
This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-analytics-module-ga4` instead.
plugins/analytics-module-ga4/package.json
+4 -2
View File
@@ -2,7 +2,8 @@
"name": "@backstage/plugin-analytics-module-ga4",
"version": "0.2.4",
"backstage": {
"role": "frontend-plugin-module"
"role": "frontend-plugin-module",
"moved": "@backstage-community/plugin-analytics-module-ga4"
},
"publishConfig": {
"access": "public",
@@ -53,5 +54,6 @@
"react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
"react-router-dom": "6.0.0-beta.0 || ^6.3.0"
},
"configSchema": "config.d.ts"
"configSchema": "config.d.ts",
"deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-analytics-module-ga4 instead."
}
plugins/analytics-module-newrelic-browser/README.md
+2 -134
View File
@@ -1,135 +1,3 @@
# Analytics Module: New Relic Browser
# Deprecated
This plugin provides an opinionated implementation of the Backstage Analytics API for New Relic Browser. Once installed and configured, analytics events will be sent to New Relic as your users navigate and use your Backstage instance.
This plugin contains no other functionality.
## Installation
1. Install the plugin package in your Backstage app:
```sh
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-analytics-module-newrelic-browser
```
2. Wire up the API implementation to your App:
```tsx
// packages/app/src/apis.ts
import {
analyticsApiRef,
configApiRef,
identityApiRef,
} from '@backstage/core-plugin-api';
import { NewRelicBrowser } from '@backstage/plugin-analytics-module-newrelic-browser';
export const apis: AnyApiFactory[] = [
// Instantiate and register the New Relic Browser API Implementation.
createApiFactory({
api: analyticsApiRef,
deps: { configApi: configApiRef, identityApi: identityApiRef },
factory: ({ configApi, identityApi }) =>
NewRelicBrowser.fromConfig(configApi, {
identityApi,
}),
}),
];
```
3. Configure the plugin in your `app-config.yaml`:
The following is the minimum configuration required to start sending analytics
events to New Relic Browser. You find this information when creating a new application
in New Relic Browser using the Copy/Paste method.
```yaml
# app-config.yaml
app:
analytics:
newRelic:
endpoint: 'bam.nr-data.net',
accountId: '1234567'
applicationId: '987654321'
licenseKey: 'NRJS-12a3456bc78de9123f4'
```
> Note: Depending on New Relic's data center you are using you'll want to change the `endpoint` to `bam.eu01.nr-data.net` for the EU data center. Refer to [this document](https://docs.newrelic.com/docs/new-relic-solutions/get-started/networks/#data-ingest) for available endpoints.
## Configuration
By default the distributed tracing and cookies features are disabled. You can enable them by adding the following to your `app-config.yaml`:
```yaml
# app-config.yaml
app:
analytics:
newRelic:
...
distributedTracing: true
cookiesEnabled: true
```
### User IDs
This plugin supports sending user context to New Relic Browser by providing a User ID. This requires instantiating the `NewRelicBrowser` instance with an `identityApi` instance passed to it, but this is optional. If omitted the plugin will not send user context to New Relic Browser.
By default the user ID is calculated as a SHA-256 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 `NewRelicBrowser`. 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:
```typescript
import {
analyticsApiRef,
configApiRef,
identityApiRef,
} from '@backstage/core-plugin-api';
import { GoogleAnalytics } from '@backstage/plugin-analytics-module-newrelic-browser';
export const apis: AnyApiFactory[] = [
createApiFactory({
api: analyticsApiRef,
deps: { configApi: configApiRef, identityApi: identityApiRef },
factory: ({ configApi, identityApi }) =>
NewRelicBrowser.fromConfig(configApi, {
identityApi,
userIdTransform: async (userEntityRef: string): Promise<string> => {
return customHashingFunction(userEntityRef);
},
}),
}),
];
```
## Development
If you would like to contribute improvements to this plugin, the easiest way to
make and test changes is to do the following:
1. Clone the main Backstage monorepo `git clone git@github.com:backstage/backstage.git`
2. Install all dependencies `yarn install`
3. If one does not exist, create an `app-config.local.yaml` file in the root of
the monorepo and add config for this plugin (see below)
4. Enter this plugin's working directory: `cd plugins/analytics-provider-newrelic-browser`
5. Start the plugin in isolation: `yarn start`
6. Navigate to the playground page at `http://localhost:3000/newrelic`
7. Open the web console to see events fire when you navigate or when you
interact with instrumented components.
Code for the isolated version of the plugin can be found inside the [/dev](./dev)
directory. Changes to the plugin are hot-reloaded.
#### Recommended Dev Config
Paste this into your `app-config.local.yaml` while developing this plugin:
```yaml
app:
analytics:
newRelic:
accountId: '1234567'
applicationId: '987654321'
licenseKey: 'NRJS-12a3456bc78de9123f4'
distributedTracingEnabled: true
cookiesEnabled: true
useEuEndpoint: false
```
This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-analytics-module-newrelic-browser` instead.
plugins/analytics-module-newrelic-browser/package.json
+4 -2
View File
@@ -2,7 +2,8 @@
"name": "@backstage/plugin-analytics-module-newrelic-browser",
"version": "0.1.4",
"backstage": {
"role": "frontend-plugin-module"
"role": "frontend-plugin-module",
"moved": "@backstage-community/plugin-analytics-module-newrelic-browser"
},
"publishConfig": {
"access": "public",
@@ -47,5 +48,6 @@
"peerDependencies": {
"react": "^16.13.1 || ^17.0.0 || ^18.0.0"
},
"configSchema": "config.d.ts"
"configSchema": "config.d.ts",
"deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-analytics-module-newrelic-browser instead."
}