@jmartins-tillster/analytics-react-native 2.21.3

package/packages/core/src/plugins/ConsentPlugin.ts

@@ -0,0 +1,200 @@
+import { Plugin } from '../plugin';
+import { PluginType } from '../types';
+import type {
+  IntegrationSettings,
+  SegmentAPIIntegration,
+  SegmentEvent,
+  TrackEventType,
+  UpdateType,
+  SegmentAPISettings,
+} from '../types';
+import type { DestinationPlugin } from '../plugin';
+import type { SegmentClient } from '../analytics';
+
+import { SEGMENT_DESTINATION_KEY } from './SegmentDestination';
+
+const CONSENT_PREF_UPDATE_EVENT = 'Segment Consent Preference';
+
+export interface CategoryConsentStatusProvider {
+  setApplicableCategories(categories: string[]): void;
+  getConsentStatus(): Promise<Record<string, boolean>>;
+  onConsentChange(cb: (updConsent: Record<string, boolean>) => void): void;
+  shutdown?(): void;
+}
+
+/**
+ * This plugin interfaces with the consent provider and it:
+ *
+ * - stamps all events with the consent metadata.
+ * - augments all destinations with a consent filter plugin that prevents events from reaching them if
+ * they are not compliant current consent setup
+ * - listens for consent change from the provider and notifies Segment
+ */
+export class ConsentPlugin extends Plugin {
+  type = PluginType.before;
+  private consentCategoryProvider: CategoryConsentStatusProvider;
+  private categories: string[] = [];
+  queuedEvents: SegmentEvent[] = [];
+  consentStarted = false;
+
+  constructor(consentCategoryProvider: CategoryConsentStatusProvider) {
+    super();
+    this.consentCategoryProvider = consentCategoryProvider;
+  }
+
+  update(_settings: SegmentAPISettings, _type: UpdateType): void {
+    const consentSettings = this.analytics?.consentSettings.get();
+    this.categories = consentSettings?.allCategories || [];
+    this.consentCategoryProvider.setApplicableCategories(this.categories);
+  }
+
+  configure(analytics: SegmentClient): void {
+    super.configure(analytics);
+    analytics.getPlugins().forEach(this.injectConsentFilterIfApplicable);
+    analytics.onPluginLoaded(this.injectConsentFilterIfApplicable);
+    this.consentCategoryProvider.onConsentChange(() => {
+      this.notifyConsentChange();
+    });
+
+    let lastDeviceAttrs = analytics.context.get()?.device;
+    analytics.context.onChange((c) => {
+      const newAttrs = c?.device;
+      if (
+        newAttrs?.adTrackingEnabled !== lastDeviceAttrs?.adTrackingEnabled ||
+        newAttrs?.advertisingId !== lastDeviceAttrs?.advertisingId ||
+        newAttrs?.trackingStatus !== lastDeviceAttrs?.trackingStatus
+      ) {
+        this.notifyConsentChange();
+      }
+      lastDeviceAttrs = newAttrs;
+    });
+  }
+
+  async execute(event: SegmentEvent): Promise<SegmentEvent | undefined> {
+    if (this.consentStarted === true) {
+      event.context = {
+        ...event.context,
+        consent: {
+          categoryPreferences:
+            await this.consentCategoryProvider.getConsentStatus(),
+        },
+      };
+      return event;
+    }
+
+    if (this.consentStarted === false) {
+      // constrain the queue to avoid running out of memory if consent is never started
+      if (this.queuedEvents.length <= 1000) {
+        this.queuedEvents.push(event);
+        return;
+      }
+      return;
+    }
+    return;
+  }
+
+  shutdown(): void {
+    this.consentCategoryProvider.shutdown?.();
+  }
+
+  private injectConsentFilterIfApplicable = (plugin: Plugin) => {
+    if (this.isDestinationPlugin(plugin)) {
+      plugin.add(
+        new ConsentFilterPlugin((event) => {
+          const allCategories =
+            this.analytics?.consentSettings.get()?.allCategories || [];
+          const settings = this.analytics?.settings.get() || {};
+          const preferences = event.context?.consent?.categoryPreferences || {};
+
+          if (plugin.key === SEGMENT_DESTINATION_KEY) {
+            const noneConsented = allCategories.every(
+              (category) => !preferences[category]
+            );
+
+            return (
+              this.isConsentUpdateEvent(event) ||
+              !this.isConsentFeatureSetup() ||
+              !(noneConsented && !this.hasUnmappedDestinations())
+            );
+          }
+
+          const integrationSettings = settings?.[plugin.key];
+          if (this.containsConsentSettings(integrationSettings)) {
+            const categories = integrationSettings.consentSettings.categories;
+            return (
+              !this.isConsentUpdateEvent(event) &&
+              categories.every((category) => preferences?.[category])
+            );
+          }
+
+          return true;
+        })
+      );
+    }
+  };
+
+  private isDestinationPlugin(plugin: Plugin): plugin is DestinationPlugin {
+    return plugin.type === PluginType.destination;
+  }
+
+  private containsConsentSettings = (
+    settings: IntegrationSettings | undefined
+  ): settings is Required<Pick<SegmentAPIIntegration, 'consentSettings'>> => {
+    return (
+      typeof (settings as SegmentAPIIntegration)?.consentSettings
+        ?.categories === 'object'
+    );
+  };
+
+  private isConsentUpdateEvent(event: SegmentEvent): boolean {
+    return (event as TrackEventType).event === CONSENT_PREF_UPDATE_EVENT;
+  }
+
+  private hasUnmappedDestinations(): boolean {
+    return (
+      this.analytics?.consentSettings.get()?.hasUnmappedDestinations === true
+    );
+  }
+
+  private isConsentFeatureSetup(): boolean {
+    return typeof this.analytics?.consentSettings.get() === 'object';
+  }
+
+  private notifyConsentChange() {
+    // actual preferences will be attached in the execute method
+    this.analytics?.track(CONSENT_PREF_UPDATE_EVENT).catch((e) => {
+      throw e;
+    });
+  }
+
+  public start() {
+    this.consentStarted = true;
+
+    this.sendQueuedEvents();
+  }
+
+  sendQueuedEvents() {
+    this.queuedEvents.forEach((event) => {
+      this.analytics?.process(event);
+    });
+    this.queuedEvents = [];
+  }
+}
+
+/**
+ * This plugin reads the consent metadata set on the context object and then drops the events
+ * if they are going into a destination which violates's set consent preferences
+ */
+class ConsentFilterPlugin extends Plugin {
+  type = PluginType.before;
+  private shouldAllowEvent: (event: SegmentEvent) => boolean;
+
+  constructor(shouldAllowEvent: (event: SegmentEvent) => boolean) {
+    super();
+    this.shouldAllowEvent = shouldAllowEvent;
+  }
+
+  execute(event: SegmentEvent): SegmentEvent | undefined {
+    return this.shouldAllowEvent(event) ? event : undefined;
+  }
+}

package/packages/core/src/plugins/DestinationMetadataEnrichment.ts

@@ -0,0 +1,67 @@
+import { DestinationPlugin, UtilityPlugin } from '../plugin';
+import { PluginType, SegmentEvent } from '../types';
+
+export class DestinationMetadataEnrichment extends UtilityPlugin {
+  type = PluginType.enrichment;
+
+  private destinationKey: string;
+
+  constructor(destinationKey: string) {
+    super();
+    this.destinationKey = destinationKey;
+  }
+
+  execute(event: SegmentEvent): SegmentEvent {
+    const pluginSettings = this.analytics?.settings.get();
+    const plugins = this.analytics?.getPlugins(PluginType.destination);
+
+    if (pluginSettings === undefined) {
+      return event;
+    }
+
+    // Disable all destinations that have a device mode plugin
+    const destinations =
+      plugins?.map((plugin) => (plugin as DestinationPlugin).key) ?? [];
+    const bundled = new Set<string>();
+
+    for (const key of destinations) {
+      if (key === this.destinationKey) {
+        continue;
+      }
+
+      if (Object.keys(pluginSettings).includes(key)) {
+        bundled.add(key);
+      }
+    }
+
+    const unbundled = new Set<string>();
+    const segmentInfo =
+      (pluginSettings[this.destinationKey] as Record<string, unknown>) ?? {};
+    const unbundledIntegrations: string[] =
+      (segmentInfo.unbundledIntegrations as string[]) ?? [];
+
+    // All active integrations, not in `bundled` are put in `unbundled`
+    // All unbundledIntegrations not in `bundled` are put in `unbundled`
+    for (const integration in pluginSettings) {
+      if (integration !== this.destinationKey && !bundled.has(integration)) {
+        unbundled.add(integration);
+      }
+    }
+    for (const integration of unbundledIntegrations) {
+      if (!bundled.has(integration)) {
+        unbundled.add(integration);
+      }
+    }
+
+    // User/event defined integrations override the cloud/device mode merge
+    const enrichedEvent: SegmentEvent = {
+      ...event,
+      _metadata: {
+        bundled: Array.from(bundled),
+        unbundled: Array.from(unbundled),
+        bundledIds: [],
+      },
+    };
+    return enrichedEvent;
+  }
+}

package/packages/core/src/plugins/QueueFlushingPlugin.ts

@@ -0,0 +1,149 @@
+import { createStore, Store } from '@segment/sovran-react-native';
+import type { SegmentClient } from '../analytics';
+import { defaultConfig } from '../constants';
+import { UtilityPlugin } from '../plugin';
+import { PluginType, SegmentEvent } from '../types';
+import { createPromise } from '../util';
+import { ErrorType, SegmentError } from '../errors';
+/**
+ * This plugin manages a queue where all events get added to after timeline processing.
+ * It takes a onFlush callback to trigger any action particular to your destination sending events.
+ * It can autotrigger a flush of the queue when it reaches the config flushAt limit.
+ */
+export class QueueFlushingPlugin extends UtilityPlugin {
+  // Gets executed last to keep the queue after all timeline processing is done
+  type = PluginType.after;
+
+  private storeKey: string;
+  private isPendingUpload = false;
+  private queueStore: Store<{ events: SegmentEvent[] }> | undefined;
+  private onFlush: (events: SegmentEvent[]) => Promise<void>;
+  private isRestoredResolve: () => void;
+  private isRestored: Promise<void>;
+  private timeoutWarned = false;
+
+  /**
+   * @param onFlush callback to execute when the queue is flushed (either by reaching the limit or manually) e.g. code to upload events to your destination
+   * @param storeKey key to store the queue in the store. Must be unique per destination instance
+   * @param restoreTimeout time in ms to wait for the queue to be restored from the store before uploading events (default: 500ms)
+   */
+  constructor(
+    onFlush: (events: SegmentEvent[]) => Promise<void>,
+    storeKey = 'events',
+    restoreTimeout = 1000
+  ) {
+    super();
+    this.onFlush = onFlush;
+    this.storeKey = storeKey;
+    const { promise, resolve } = createPromise<void>(restoreTimeout);
+    this.isRestored = promise;
+    this.isRestoredResolve = resolve;
+  }
+
+  configure(analytics: SegmentClient): void {
+    super.configure(analytics);
+
+    const config = analytics?.getConfig() ?? defaultConfig;
+
+    // Create its own storage per SegmentDestination instance to support multiple instances
+    this.queueStore = createStore(
+      { events: [] as SegmentEvent[] },
+      {
+        persist: {
+          storeId: `${config.writeKey}-${this.storeKey}`,
+          persistor: config.storePersistor,
+          saveDelay: config.storePersistorSaveDelay ?? 0,
+          onInitialized: () => {
+            this.isRestoredResolve();
+          },
+        },
+      }
+    );
+  }
+
+  async execute(event: SegmentEvent): Promise<SegmentEvent | undefined> {
+    await this.queueStore?.dispatch((state) => {
+      const events = [...state.events, event];
+      return { events };
+    });
+    return event;
+  }
+
+  /**
+   * Calls the onFlush callback with the events in the queue
+   */
+  async flush() {
+    // Wait for the queue to be restored
+    try {
+      await this.isRestored;
+
+      if (this.timeoutWarned === true) {
+        this.analytics?.logger.info('Flush triggered successfully.');
+
+        this.timeoutWarned = false;
+      }
+    } catch (e) {
+      // If the queue is not restored before the timeout, we will notify but not block flushing events
+      if (this.timeoutWarned === false) {
+        this.analytics?.reportInternalError(
+          new SegmentError(
+            ErrorType.InitializationError,
+            'Queue restoration timeout',
+            e
+          )
+        );
+
+        this.analytics?.logger.warn(
+          'Flush triggered but queue restoration and settings loading not complete. Flush will be retried.',
+          e
+        );
+
+        this.timeoutWarned = true;
+      }
+    }
+
+    const events = (await this.queueStore?.getState(true))?.events ?? [];
+    if (!this.isPendingUpload) {
+      try {
+        this.isPendingUpload = true;
+        await this.onFlush(events);
+      } finally {
+        this.isPendingUpload = false;
+      }
+    }
+  }
+
+  /**
+   * Removes one or multiple events from the queue
+   * @param events events to remove
+   */
+  async dequeue(events: SegmentEvent | SegmentEvent[]) {
+    await this.queueStore?.dispatch((state) => {
+      const eventsToRemove = Array.isArray(events) ? events : [events];
+
+      if (eventsToRemove.length === 0 || state.events.length === 0) {
+        return state;
+      }
+
+      const setToRemove = new Set(eventsToRemove);
+      const filteredEvents = state.events.filter((e) => !setToRemove.has(e));
+      return { events: filteredEvents };
+    });
+  }
+  /**
+   * Clear all events from the queue
+   */
+  async dequeueEvents() {
+    await this.queueStore?.dispatch(() => {
+      return { events: [] };
+    });
+  }
+
+  /**
+   * * Returns the count of items in the queue
+   */
+  async pendingEvents() {
+    const events = (await this.queueStore?.getState(true))?.events ?? [];
+    return events.length;
+  }
+}

package/packages/core/src/plugins/SegmentDestination.ts

@@ -0,0 +1,153 @@
+import { DestinationPlugin } from '../plugin';
+import {
+  PluginType,
+  SegmentAPIIntegration,
+  SegmentAPISettings,
+  SegmentEvent,
+  UpdateType,
+} from '../types';
+import { chunk, createPromise, getURL } from '../util';
+import { uploadEvents } from '../api';
+import type { SegmentClient } from '../analytics';
+import { DestinationMetadataEnrichment } from './DestinationMetadataEnrichment';
+import { QueueFlushingPlugin } from './QueueFlushingPlugin';
+import { defaultApiHost } from '../constants';
+import { checkResponseForErrors, translateHTTPError } from '../errors';
+import { defaultConfig } from '../constants';
+
+const MAX_EVENTS_PER_BATCH = 100;
+const MAX_PAYLOAD_SIZE_IN_KB = 500;
+export const SEGMENT_DESTINATION_KEY = 'Segment.io';
+
+export class SegmentDestination extends DestinationPlugin {
+  type = PluginType.destination;
+  key = SEGMENT_DESTINATION_KEY;
+  private apiHost?: string;
+  private settingsResolve: () => void;
+  private settingsPromise: Promise<void>;
+
+  constructor() {
+    super();
+    // We don't timeout this promise. We strictly need the response from Segment before sending things
+    const { promise, resolve } = createPromise<void>();
+    this.settingsPromise = promise;
+    this.settingsResolve = resolve;
+  }
+
+  private sendEvents = async (events: SegmentEvent[]): Promise<void> => {
+    if (events.length === 0) {
+      return Promise.resolve();
+    }
+
+    // We're not sending events until Segment has loaded all settings
+    await this.settingsPromise;
+
+    const config = this.analytics?.getConfig() ?? defaultConfig;
+
+    const chunkedEvents: SegmentEvent[][] = chunk(
+      events,
+      config.maxBatchSize ?? MAX_EVENTS_PER_BATCH,
+      MAX_PAYLOAD_SIZE_IN_KB
+    );
+
+    let sentEvents: SegmentEvent[] = [];
+    let numFailedEvents = 0;
+
+    await Promise.all(
+      chunkedEvents.map(async (batch: SegmentEvent[]) => {
+        try {
+          const res = await uploadEvents({
+            writeKey: config.writeKey,
+            url: this.getEndpoint(),
+            events: batch,
+          });
+          checkResponseForErrors(res);
+          sentEvents = sentEvents.concat(batch);
+        } catch (e) {
+          this.analytics?.reportInternalError(translateHTTPError(e));
+          this.analytics?.logger.warn(e);
+          numFailedEvents += batch.length;
+        } finally {
+          await this.queuePlugin.dequeue(sentEvents);
+        }
+      })
+    );
+
+    if (sentEvents.length) {
+      if (config.debug === true) {
+        this.analytics?.logger.info(`Sent ${sentEvents.length} events`);
+      }
+    }
+
+    if (numFailedEvents) {
+      this.analytics?.logger.error(`Failed to send ${numFailedEvents} events.`);
+    }
+
+    return Promise.resolve();
+  };
+
+  private readonly queuePlugin = new QueueFlushingPlugin(this.sendEvents);
+
+  private getEndpoint(): string {
+    const config = this.analytics?.getConfig();
+    const hasProxy = !!(config?.proxy ?? '');
+    const useSegmentEndpoints = Boolean(config?.useSegmentEndpoints);
+    let baseURL = '';
+    let endpoint = '';
+    if (hasProxy) {
+      //baseURL is always config?.proxy if hasProxy
+      baseURL = config?.proxy ?? '';
+      if (useSegmentEndpoints) {
+        const isProxyEndsWithSlash = baseURL.endsWith('/');
+        endpoint = isProxyEndsWithSlash ? 'b' : '/b';
+      }
+    } else {
+      baseURL = this.apiHost ?? defaultApiHost;
+    }
+    try {
+      return getURL(baseURL, endpoint);
+    } catch (error) {
+      console.error('Error in getEndpoint:', `fallback to ${defaultApiHost}`);
+      return defaultApiHost;
+    }
+  }
+  configure(analytics: SegmentClient): void {
+    super.configure(analytics);
+
+    // If the client has a proxy we don't need to await for settings apiHost, we can send events directly
+    // Important! If new settings are required in the future you probably want to change this!
+    if (analytics.getConfig().proxy !== undefined) {
+      this.settingsResolve();
+    }
+
+    // Enrich events with the Destination metadata
+    this.add(new DestinationMetadataEnrichment(SEGMENT_DESTINATION_KEY));
+    this.add(this.queuePlugin);
+  }
+
+  // We block sending stuff to segment until we get the settings
+  update(settings: SegmentAPISettings, _type: UpdateType): void {
+    const segmentSettings = settings.integrations[
+      this.key
+    ] as SegmentAPIIntegration;
+    if (
+      segmentSettings?.apiHost !== undefined &&
+      segmentSettings?.apiHost !== null
+    ) {
+      //assign the api host from segment settings (domain/v1)
+      this.apiHost = `https://${segmentSettings.apiHost}/b`;
+    }
+    this.settingsResolve();
+  }
+
+  execute(event: SegmentEvent): Promise<SegmentEvent | undefined> {
+    // Execute the internal timeline here, the queue plugin will pick up the event and add it to the queue automatically
+    const enrichedEvent = super.execute(event);
+    return enrichedEvent;
+  }
+
+  async flush() {
+    // Wait until the queue is done restoring before flushing
+    return this.queuePlugin.flush();
+  }
+}