public final class Analytics

  1. Object
  2. Analytics

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("tutorial_complete").param("seconds", 42).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.

Methods

public static void addProvider(AnalyticsProvider provider)Registers a provider and immediately supplies it with the current AnalyticsContext and consent state.
public static void removeProvider(AnalyticsProvider provider)Removes a previously registered provider.
public static void clearProviders()Removes every registered provider.
public static List<AnalyticsProvider> getProviders()The currently registered providers.
public static void setConsentMode(ConsentMode mode)Sets the consent mode that governs behaviour before an explicit consent choice is recorded.
public static ConsentMode getConsentMode()The active consent mode.
public static void setConsent(AnalyticsConsent newConsent)Records the user’s consent choice, persists it and notifies every provider.
public static AnalyticsConsent getConsent()The currently recorded consent, loading it from Preferences on first access.
public static void screen(String name, String referrer)Records a screen / page view across all providers.
public static void event(AnalyticsEvent event)Records a named event across all providers.
public static void autoEvent(String name, String category, Map<String, Object> params)Deprecated Internal hook used by the framework to auto-instrument built-in APIs (purchases, sharing, …).
public static void setUserId(String id)Associates subsequent activity with a user id.
public static void setUserProperty(String key, String value)Sets a user property / custom dimension.
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").
public static void clearDimension(String key)Removes a single custom dimension.
public static void clearDimensions()Removes every custom dimension.
public static Map<String, String> getDimensions()The current custom dimensions.
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.
public static void crash(AnalyticsCrashReport report)Reports a crash / exception across all providers.
public static void flush()Flushes any buffered events in every provider.
public static String clientId()The pseudonymous client id, generating and persisting one on first use.
public static String resetClientId()Generates a fresh pseudonymous client id, persists it and re-initialises every provider with the new identity.

Inherited methods

From Object

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

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 AnalyticsProvider
the provider to add, ignored if null

removeProvider

public static void removeProvider(AnalyticsProvider provider)
Removes a previously registered provider.

Parameters

provider AnalyticsProvider
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 ConsentMode
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 AnalyticsConsent
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 String
the screen name
referrer String
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 AnalyticsEvent
the event

autoEvent

public static void autoEvent(String name, String category, Map<String, Object> params)
Deprecated. Internal framework auto-instrumentation hook; not intended for app use.
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 String
the event name
category String
the event category, may be null
params Map<String, Object>
optional event parameters, may be null

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 String
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 String
the property name
value String
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 String
the dimension key
value String
the dimension value, or null to remove the key

clearDimension

public static void clearDimension(String key)
Removes a single custom dimension.

Parameters

key String
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 Throwable
the captured exception, may be null
message String
a human readable description, may be null
fatal boolean
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 AnalyticsCrashReport
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