npm package: @pfeifferj/backstage-plugin-analytics-generic
Description: This plugin provides a generic implementation of the Backstage Analytics API for publishing events to POST endpoints such as knative sinks.
Latest version: 0.1.1

# Analytics Module: Generic

This plugin provides a generic implementation of the Backstage Analytics
API for publishing events to POST endpoints such as knative sinks.

This module is made to work with backstage's built-in analytics plugin. The usage guide to start tracking analytics for your plugins can be found here: https://backstage.io/docs/plugins/analytics/

## Installation

This plugin supports both traditional Backstage installation and Red Hat Developer Hub (RHDH) dynamic plugin deployment.

### Traditional Backstage Installation

1. Install the plugin package in your Backstage app:

```sh
# From your Backstage root directory
yarn add --cwd packages/app @pfeifferj/backstage-plugin-analytics-generic
```

2. Wire up the API implementation to your App:

```tsx
// packages/app/src/apis.ts
import {
  	AnyApiFactory,
  	createApiFactory,
  	discoveryApiRef,
	analyticsApiRef,
	configApiRef,
	errorApiRef,
	identityApiRef, // optional: if you want to add user-context to events
} from '@backstage/core-plugin-api';

import { GenericAnalyticsAPI } from '@pfeifferj/backstage-plugin-analytics-generic';
import { catalogApiRef } from '@backstage/plugin-catalog-react';

export const apis: AnyApiFactory[] = [
	...
	// Instantiate and register the Generic Analytics API Implementation.

  	createApiFactory({
    	api: analyticsApiRef,
    	deps: {
      		configApi: configApiRef,
      		errorApi: errorApiRef,
      		identityApi: identityApiRef,
      		catalogApi: catalogApiRef,
    	},
		factory: ({ configApi, errorApi, identityApi, catalogApi }) =>
      		GenericAnalyticsAPI.fromConfig(
        		configApi,
        		errorApi,
        		identityApi,
        		catalogApi,
			),
  	}),
	...
];
```

3. Configure the plugin in your `app-config.yaml`:

The following is the minimum configuration required to start sending analytics
events to a Knative sink. All that's needed is your Knative sink Host:

```yaml
# app-config.yaml
app:
  analytics:
    generic:
      host: ${ANALYTICS_GENERIC_HOST}
      interval: ${ANALYTICS_GENERIC_INTERVAL} # interval in minutes to ship logs, set to 0 for instant streaming. default: 30 mins
      basicAuthToken: ${ANALYTICS_GENERIC_BASIC_AUTH} # basic auth token (optional)
      bearerAuthToken: ${ANALYTICS_GENERIC_BEARER_TOKEN} # bearer token for JWT/OAuth (optional)
      debug: true # logs events & debugging info in console & frontend. default: false (optional)
      includeTeamMetadata: true # include team metadata from catalog API. default: false (optional)

...
backend:
  cors:
    ...
	Access-Control-Allow-Origin: '*' # your endpoint
```

## Authentication

The plugin supports two authentication methods for securing your analytics endpoint:

- **Basic Authentication**: Set `basicAuthToken` to a base64-encoded `username:password` string
- **Bearer Token**: Set `bearerAuthToken` to a JWT token or OAuth bearer token

If both are configured, basic authentication takes precedence. Choose the method that matches your endpoint's authentication requirements.

### Red Hat Developer Hub (RHDH) Dynamic Plugin Installation

For RHDH deployments, you can install this plugin dynamically without rebuilding your application.

#### Using NPM Package

Add to your RHDH dynamic plugins configuration:

```yaml
global:
  dynamic:
    plugins:
      - package: '@pfeifferj/backstage-plugin-analytics-generic-dynamic@latest'
        disabled: false
        pluginConfig:
          app:
            analytics:
              generic:
                host: ${ANALYTICS_GENERIC_HOST}
                interval: ${ANALYTICS_GENERIC_INTERVAL}
                basicAuthToken: ${ANALYTICS_GENERIC_BASIC_AUTH}
                bearerAuthToken: ${ANALYTICS_GENERIC_BEARER_TOKEN}
                debug: true
                includeTeamMetadata: true
```