# Class Analytics

java.lang.Object
com.codename1.analytics.Analytics

public final class Analytics extends Object

The application-facing entry point for analytics. `Analytics` holds the set of registered `providers`, the user's consent state and the pseudonymous client id, and fans every reporting call out to all providers -- but only once the relevant consent has been satisfied.

#### Typical setup

    // register one or more providers (no reflection -- explicit instances)
    Analytics.addProvider(new CodenameOneAnalyticsProvider());
    Analytics.addProvider(new GoogleAnalyticsProvider("G-XXXX", "api-secret"));

    // GDPR: nothing is sent until the user grants consent (opt-in is the default)
    Analytics.setConsent(AnalyticsConsent.granted());

    Analytics.screen("Home", null);
    Analytics.event(AnalyticsEvent.create("purchase").param("value", 9.99).build());

#### Consent and privacy

The `ConsentMode` governs behaviour before an explicit choice is recorded. In the default `ConsentMode.OPT_IN` mode reporting calls are silently dropped until `setConsent(AnalyticsConsent)` grants the matching category. The consent choice and the client id are persisted in `Preferences` so they survive restarts. The client id is not derived from any hardware identifier and can be cleared with `resetClientId()` to honour an erasure request.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `addProvider(AnalyticsProvider provider)`
  Registers a provider and immediately supplies it with the current `AnalyticsContext` and consent state.
  `static void`
  `autoEvent(String name, String category, Map<String,Object> params)`
  Internal hook used by the framework to auto-instrument built-in APIs (purchases, sharing, ...).
  `static void`
  `clearDimension(String key)`
  Removes a single custom dimension.
  `static void`
  `clearDimensions()`
  Removes every custom dimension.
  `static void`
  `clearProviders()`
  Removes every registered provider.
  `static String`
  `clientId()`
  The pseudonymous client id, generating and persisting one on first use.
  `static void`
  `crash(AnalyticsCrashReport report)`
  Reports a crash / exception across all providers.
  `static void`
  `crash(Throwable throwable, String message, boolean fatal)`
  Reports a crash / exception to the registered analytics providers as an exception signal -- for example GA4's `app_exception` or the Firebase equivalent -- so exception counts surface alongside your usage metrics.
  `static void`
  `event(AnalyticsEvent event)`
  Records a named event across all providers.
  `static void`
  `flush()`
  Flushes any buffered events in every provider.
  `static AnalyticsConsent`
  `getConsent()`
  The currently recorded consent, loading it from `Preferences` on first access.
  `static ConsentMode`
  `getConsentMode()`
  The active consent mode.
  `static Map<String,String>`
  `getDimensions()`
  The current custom dimensions.
  `static List<AnalyticsProvider>`
  `getProviders()`
  The currently registered providers.
  `static void`
  `removeProvider(AnalyticsProvider provider)`
  Removes a previously registered provider.
  `static String`
  `resetClientId()`
  Generates a fresh pseudonymous client id, persists it and re-initialises every provider with the new identity.
  `static void`
  `screen(String name, String referrer)`
  Records a screen / page view across all providers.
  `static void`
  `setConsent(AnalyticsConsent newConsent)`
  Records the user's consent choice, persists it and notifies every provider.
  `static void`
  `setConsentMode(ConsentMode mode)`
  Sets the consent mode that governs behaviour before an explicit consent choice is recorded.
  `static void`
  `setDimension(String key, String value)`
  Sets an app-scoped custom dimension used by the cloud console to segment reports (for example `"plan"` or `"role"`).
  `static void`
  `setUserId(String id)`
  Associates subsequent activity with a user id.
  `static void`
  `setUserProperty(String key, String value)`
  Sets a user property / custom dimension.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### addProvider

    public static void addProvider(AnalyticsProvider provider)

    Registers a provider and immediately supplies it with the current `AnalyticsContext` and consent state.

    ###### Parameters

    - `provider`: the provider to add, ignored if null

  - ### removeProvider

    public static void removeProvider(AnalyticsProvider provider)

    Removes a previously registered provider.

    ###### Parameters

    - `provider`: the provider to remove

  - ### clearProviders

    public static void clearProviders()
    Removes every registered provider.

  - ### getProviders

    public static List<AnalyticsProvider> getProviders()

    The currently registered providers.

    ###### Returns

    an immutable copy of the provider list

  - ### setConsentMode

    public static void setConsentMode(ConsentMode mode)

    Sets the consent mode that governs behaviour before an explicit consent choice is recorded. Defaults to `ConsentMode.OPT_IN`.

    ###### Parameters

    - `mode`: the consent mode, ignored if null

  - ### getConsentMode

    public static ConsentMode getConsentMode()

    The active consent mode.

    ###### Returns

    the consent mode

  - ### setConsent

    public static void setConsent(AnalyticsConsent newConsent)

    Records the user's consent choice, persists it and notifies every provider. Passing null clears the stored choice (reverting to the implicit behaviour of the current `ConsentMode`).

    ###### Parameters

    - `newConsent`: the consent state, or null to clear

  - ### getConsent

    public static AnalyticsConsent getConsent()

    The currently recorded consent, loading it from `Preferences` on first access. Returns null if the user has not made an explicit choice.

    ###### Returns

    the consent state or null

  - ### screen

    public static void screen(String name, String referrer)

    Records a screen / page view across all providers. No-op unless the analytics consent category is satisfied.

    ###### Parameters

    - `name`: the screen name

    - `referrer`: the previous screen, may be null

  - ### event

    public static void event(AnalyticsEvent event)

    Records a named event across all providers. No-op unless the analytics consent category is satisfied.

    ###### Parameters

    - `event`: the event

  - ### autoEvent

    public static void autoEvent(String name, String category, Map<String,Object> params)

    Internal hook used by the framework to auto-instrument built-in APIs (purchases, sharing, ...). It builds an `AnalyticsEvent` and routes it through the normal consent-gated `event(AnalyticsEvent)` path, so it is automatically a no-op when consent has not been granted. As a fast path it does nothing at all when no provider is registered, which keeps the cost of the framework call sites negligible when analytics is not in use. Never throws into the caller.

    ###### Parameters

    - `name`: the event name

    - `category`: the event category, may be null

    - `params`: optional event parameters, may be null

    ###### Deprecated

    Internal framework auto-instrumentation hook; not intended for app use.

  - ### setUserId

    public static void setUserId(String id)

    Associates subsequent activity with a user id. No-op unless the personalization consent category is satisfied.

    ###### Parameters

    - `id`: the user id, or null to clear

  - ### setUserProperty

    public static void setUserProperty(String key, String value)

    Sets a user property / custom dimension. No-op unless the analytics consent category is satisfied.

    ###### Parameters

    - `key`: the property name

    - `value`: the property value

  - ### setDimension

    public static void setDimension(String key, String value)

    Sets an app-scoped custom dimension used by the cloud console to segment reports (for example `"plan"` or `"role"`). Dimensions are persisted in `Preferences` so they survive restarts and are sent with every first-party batch. Passing a null value removes the key. Null or empty keys are ignored.

    ###### Parameters

    - `key`: the dimension key

    - `value`: the dimension value, or null to remove the key

  - ### clearDimension

    public static void clearDimension(String key)

    Removes a single custom dimension.

    ###### Parameters

    - `key`: the dimension key

  - ### clearDimensions

    public static void clearDimensions()
    Removes every custom dimension.

  - ### getDimensions

    public static Map<String,String> getDimensions()

    The current custom dimensions.

    ###### Returns

    a defensive, insertion-ordered copy of the dimension map

  - ### crash

    public static void crash(Throwable throwable, String message, boolean fatal)

    Reports a crash / exception to the registered analytics providers as an exception signal -- for example GA4's `app_exception` or the Firebase equivalent -- so exception counts surface alongside your usage metrics. No-op unless the crash reporting consent category is satisfied.

    This is deliberately separate from Codename One Crash Protection (`CrashProtection`). Crash Protection is a dedicated crash-capture pipeline that records full, symbolicated stack traces to the build cloud crash console for debugging. This method only emits a lightweight exception event to whichever analytics backends you have registered. The two subsystems are independent: use Crash Protection to diagnose crashes, use `Analytics.crash` when you also want exception events in your analytics; you can enable either or both.

    ###### Parameters

    - `throwable`: the captured exception, may be null

    - `message`: a human readable description, may be null

    - `fatal`: whether the exception terminated the application

  - ### crash

    public static void crash(AnalyticsCrashReport report)

    Reports a crash / exception across all providers. No-op unless the crash reporting consent category is satisfied.

    ###### Parameters

    - `report`: the crash report

  - ### flush

    public static void flush()
    Flushes any buffered events in every provider.

  - ### clientId

    public static String clientId()

    The pseudonymous client id, generating and persisting one on first use. Not derived from any hardware identifier.

    ###### Returns

    the client id

  - ### resetClientId

    public static String resetClientId()

    Generates a fresh pseudonymous client id, persists it and re-initialises every provider with the new identity. Use this to honour a "right to be forgotten" / erasure request from the user.

    ###### Returns

    the new client id