Merge pull request #8508 from backstage/mob/expalytics

core-plugin-api: mark AnalyticsApi as experimental
backstage · Dec 16, 2021 · 7bd536c · 7bd536c
2 parents 64a5a09 + 18d4f50
commit 7bd536c
Show file tree

Hide file tree

Showing 6 changed files with 35 additions and 23 deletions.
diff --git a/.changeset/cool-cows-report.md b/.changeset/cool-cows-report.md
@@ -0,0 +1,5 @@
+---
+'@backstage/core-plugin-api': patch
+---
+
+Deprecated the `AnyAnalyticsContext` type and mark the `AnalyticsApi` experimental.
diff --git a/packages/core-plugin-api/api-report.md b/packages/core-plugin-api/api-report.md
@@ -35,25 +35,26 @@ export type AlertMessage = {
   severity?: 'success' | 'info' | 'warning' | 'error';
 };
 
-// @public
+// @alpha
 export type AnalyticsApi = {
   captureEvent(event: AnalyticsEvent): void;
 };
 
-// @public
+// @alpha
 export const analyticsApiRef: ApiRef<AnalyticsApi>;
 
-// @public
+// @alpha
 export const AnalyticsContext: (options: {
   attributes: Partial<AnalyticsContextValue>;
   children: ReactNode;
 }) => JSX.Element;
 
-// @public
-export type AnalyticsContextValue = CommonAnalyticsContext &
-  AnyAnalyticsContext;
+// @alpha
+export type AnalyticsContextValue = CommonAnalyticsContext & {
+  [param in string]: string | boolean | number | undefined;
+};
 
-// @public
+// @alpha
 export type AnalyticsEvent = {
   action: string;
   subject: string;
@@ -62,12 +63,12 @@ export type AnalyticsEvent = {
   context: AnalyticsContextValue;
 };
 
-// @public
+// @alpha
 export type AnalyticsEventAttributes = {
   [attribute in string]: string | boolean | number;
 };
 
-// @public
+// @alpha
 export type AnalyticsTracker = {
   captureEvent: (
     action: string,
@@ -79,7 +80,7 @@ export type AnalyticsTracker = {
   ) => void;
 };
 
-// @public
+// @public @deprecated
 export type AnyAnalyticsContext = {
   [param in string]: string | boolean | number | undefined;
 };
@@ -282,7 +283,7 @@ export type BootErrorPageProps = {
   error: Error;
 };
 
-// @public
+// @alpha
 export type CommonAnalyticsContext = {
   pluginId: string;
   routeRef: string;
@@ -820,7 +821,7 @@ export type TypesToApiRefs<T> = {
   [key in keyof T]: ApiRef<T[key]>;
 };
 
-// @public
+// @alpha
 export function useAnalytics(): AnalyticsTracker;
 
 // @public

diff --git a/packages/core-plugin-api/src/analytics/AnalyticsContext.tsx b/packages/core-plugin-api/src/analytics/AnalyticsContext.tsx
@@ -60,7 +60,7 @@ export const useAnalyticsContext = (): AnalyticsContextValue => {
  * Analytics contexts are additive, meaning the context ultimately emitted with
  * an event is the combination of all contexts in the parent tree.
  *
- * @public
+ * @alpha
  */
 export const AnalyticsContext = (options: {
   attributes: Partial<AnalyticsContextValue>;

diff --git a/packages/core-plugin-api/src/analytics/types.ts b/packages/core-plugin-api/src/analytics/types.ts
@@ -17,7 +17,7 @@
 /**
  * Common analytics context attributes.
  *
- * @public
+ * @alpha
  */
 export type CommonAnalyticsContext = {
   /**
@@ -40,6 +40,7 @@ export type CommonAnalyticsContext = {
  * Allows arbitrary scalar values as context attributes too.
  *
  * @public
+ * @deprecated Will be removed, use `AnalyticsContextValue` instead
  */
 export type AnyAnalyticsContext = {
   [param in string]: string | boolean | number | undefined;
@@ -48,7 +49,8 @@ export type AnyAnalyticsContext = {
 /**
  * Analytics context envelope.
  *
- * @public
+ * @alpha
  */
-export type AnalyticsContextValue = CommonAnalyticsContext &
-  AnyAnalyticsContext;
+export type AnalyticsContextValue = CommonAnalyticsContext & {
+  [param in string]: string | boolean | number | undefined;
+};
diff --git a/packages/core-plugin-api/src/analytics/useAnalytics.tsx b/packages/core-plugin-api/src/analytics/useAnalytics.tsx
@@ -35,7 +35,7 @@ function useAnalyticsApi(): AnalyticsApi {
 /**
  * Gets a pre-configured analytics tracker.
  *
- * @public
+ * @alpha
  */
 export function useAnalytics(): AnalyticsTracker {
   const trackerRef = useRef<Tracker | null>(null);

diff --git a/packages/core-plugin-api/src/apis/definitions/AnalyticsApi.ts b/packages/core-plugin-api/src/apis/definitions/AnalyticsApi.ts
@@ -21,7 +21,7 @@ import { AnalyticsContextValue } from '../../analytics/types';
  * Represents an event worth tracking in an analytics system that could inform
  * how users of a Backstage instance are using its features.
  *
- * @public
+ * @alpha
  */
 export type AnalyticsEvent = {
   /**
@@ -79,7 +79,7 @@ export type AnalyticsEvent = {
  * A structure allowing other arbitrary metadata to be provided by analytics
  * event emitters.
  *
- * @public
+ * @alpha
  */
 export type AnalyticsEventAttributes = {
   [attribute in string]: string | boolean | number;
@@ -89,7 +89,7 @@ export type AnalyticsEventAttributes = {
  * Represents a tracker with methods that can be called to track events in a
  * configured analytics service.
  *
- * @public
+ * @alpha
  */
 export type AnalyticsTracker = {
   captureEvent: (
@@ -103,6 +103,8 @@ export type AnalyticsTracker = {
 };
 
 /**
+ * **EXPERIMENTAL**
+ *
  * The Analytics API is used to track user behavior in a Backstage instance.
  *
  * @remarks
@@ -111,7 +113,7 @@ export type AnalyticsTracker = {
  * useAnalytics() hook. This will return a pre-configured AnalyticsTracker
  * with relevant methods for instrumentation.
  *
- * @public
+ * @alpha
  */
 export type AnalyticsApi = {
   /**
@@ -122,9 +124,11 @@ export type AnalyticsApi = {
 };
 
 /**
+ * **EXPERIMENTAL**
+ *
  * The {@link ApiRef} of {@link AnalyticsApi}.
  *
- * @public
+ * @alpha
  */
 export const analyticsApiRef: ApiRef<AnalyticsApi> = createApiRef({
   id: 'core.analytics',