Initial identity-awareness implementation for GA.

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

plugins/analytics-module-ga/README.md

@@ -14,15 +14,22 @@ This plugin contains no other functionality.
 
 ```tsx
 // packages/app/src/apis.ts
-import { analyticsApiRef, configApiRef } from '@backstage/core-plugin-api';
+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 },
-    factory: ({ configApi }) => GoogleAnalytics.fromConfig(configApi),
+    deps: { configApi: configApiRef, identityApi: identityApiRef },
+    factory: ({ configApi, identityApi }) =>
+      GoogleAnalytics.fromConfig(configApi, {
+        identityApi,
+      }),
   }),
 ];
 ```
@@ -92,6 +99,66 @@ app:
           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 custom implementation of the `identityApi` that
+resolves a `userEntityRef` of the form `PrivateUser:namespace/YOUR-VALUE`. For
+example:
+
+```typescript
+export const apis: AnyApiFactory[] = [
+  createApiFactory({
+    api: analyticsApiRef,
+    deps: { config: configApiRef, identityApi: identityApiRef },
+    factory: ({ identityApi, config }) => {
+      return new PseudononymizedIdentity(identityApi);
+    },
+  }),
+];
+
+class PseudononymizedIdentity implements IdentityApi {
+  constructor(private actualApi: IdentityApi) {}
+  async getBackstageIdentity(): Promise<BackstageUserIdentity> {
+    const { email = 'someone' } = await this.actualApi.getProfileInfo();
+    const hashedEmail = customHashingFunction(email);
+
+    return {
+      type: 'user',
+      userEntityRef: `PrivateUser:default/${hashedEmail}`,
+      ownershipEntityRefs: [],
+    };
+  }
+  // ...
+}
+```
+
 ### Debugging and Testing
 
 In pre-production environments, you may wish to set additional configurations
@@ -147,3 +214,4 @@ app:
 
 [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