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());

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 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