FirebaseAnalytics

@DataCollectionPurpose(dataTypes = [SemanticType.ST_ANALYTICS_ID, SemanticType.ST_PAYMENTS_TRANSACTION_INFO, SemanticType.ST_HARDWARE_ID, SemanticType.ST_IDENTIFYING_ID, SemanticType.ST_COARSE_LOCATION], collectionPurposes = [CollectionPurpose.CP_ANALYTICS])
class FirebaseAnalytics


The top level Firebase Analytics singleton that provides methods for logging events and setting user properties. See the developer guides for general information on using Firebase Analytics in your apps.

Applications can get an instance of this class by calling getInstance. getInstance is thread safe and can be called from any thread.

Summary

Nested types

The status value of the consent type.

The type of consent to set.

An Event is an important occurrence in your app that you want to measure.

Params supply information that contextualize Events.

A UserProperty is an attribute that describes the app-user.

Public functions

Task<String?>
@SuppressViolation(value = "catch_specific_exceptions")
getAppInstanceId()

Retrieves the app instance id from the service, or null if ANALYTICS_STORAGE has been set to DENIED.

java-static FirebaseAnalytics
@RequiresPermission(allOf = [Manifest.permission.INTERNET, Manifest.permission.ACCESS_NETWORK_STATE, Manifest.permission.WAKE_LOCK])
@Keep
getInstance(context: Context)

Returns the singleton FirebaseAnalytics interface.

Task<Long?>
@SuppressViolation(value = "catch_specific_exceptions")
getSessionId()

Retrieves the session id from the client.

Unit
logEvent(name: @Size(min = 1, max = 40) String, params: Bundle?)

Logs an app event.

Unit

Clears all analytics data for this app from the device and resets the app instance id.

Unit

Sets whether analytics collection is enabled for this app on this device.

Unit

Sets the applicable end user consent state (e.g., for device identifiers) for this app on this device.

Unit
@MainThread
@Keep
setCurrentScreen(
    activity: Activity,
    screenName: @Size(min = 1, max = 36) String?,
    screenClassOverride: @Size(min = 1, max = 36) String?
)

This function is deprecated.

To log screen view events, call mFirebaseAnalytics.logEvent(FirebaseAnalytics.Event.SCREEN_VIEW, params) instead.

Unit

Adds parameters that will be set on every event logged from the SDK, including automatic ones.

Unit

Sets the duration of inactivity that terminates the current session.

Unit

Sets the user ID property.

Unit
setUserProperty(
    name: @Size(min = 1, max = 24) String,
    value: @Size(max = 36) String?
)

Sets a user property to a given value.

Extension functions

inline Unit

Fluent version of FirebaseAnalytics.logEvent.

inline Unit

This function is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

inline Unit
FirebaseAnalytics.setConsent(crossinline block: ConsentBuilder.() -> Unit)

Fluent version of FirebaseAnalytics.setConsent.

inline Unit
FirebaseAnalytics.setConsent(crossinline block: ConsentBuilder.() -> Unit)

This function is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

Public functions

getAppInstanceId

@SuppressViolation(value = "catch_specific_exceptions")
fun getAppInstanceId(): Task<String?>

Retrieves the app instance id from the service, or null if ANALYTICS_STORAGE has been set to DENIED.

Returns
Task<String?>

Task with the result of the retrieval

See also
setConsent

getInstance

@RequiresPermission(allOf = [Manifest.permission.INTERNET, Manifest.permission.ACCESS_NETWORK_STATE, Manifest.permission.WAKE_LOCK])
@Keep
java-static fun getInstance(context: Context): FirebaseAnalytics

Returns the singleton FirebaseAnalytics interface.

Parameters
context: Context

the context used to initialize Firebase Analytics. Must not be null.

getSessionId

@SuppressViolation(value = "catch_specific_exceptions")
fun getSessionId(): Task<Long?>

Retrieves the session id from the client. Returns null if ANALYTICS_STORAGE has been set to DENIED or session is expired.

Returns
Task<Long?>

Task with the result of the retrieval

See also
setConsent

logEvent

fun logEvent(name: @Size(min = 1, max = 40) String, params: Bundle?): Unit

Logs an app event. The event can have up to 25 parameters. Events with the same name must have the same parameters. Up to 500 event names are supported. Using predefined Event and/or Param is recommended for optimal reporting.

Parameters
name: @Size(min = 1, max = 40) String

The name of the event. Should contain 1 to 40 alphanumericcharacters or underscores. The name must start with an alphabeticcharacter. Some event names are reserved. See Event for the list of reserved event names. The "firebase_", "google_" and "ga_" prefixes are reserved and should not be used. Note that event names are case-sensitive and that logging two events whose names differ only in case will result in two distinct events.

params: Bundle?

The map of event parameters. Passing null indicates that the event has no parameters. Parameter names can be up to 40 characters long and must start with an alphabeticcharacter and contain only alphanumericcharacters and underscores. String, long and double param types are supported. String parameter values can be up to 100 characters long. The "firebase_", "google_" and "ga_" prefixes are reserved and should not be used for parameter names.

resetAnalyticsData

fun resetAnalyticsData(): Unit

Clears all analytics data for this app from the device and resets the app instance id.

setAnalyticsCollectionEnabled

fun setAnalyticsCollectionEnabled(enabled: Boolean): Unit

Sets whether analytics collection is enabled for this app on this device. This setting is persisted across app sessions. By default it is enabled.

Parameters
enabled: Boolean

Whether analytics collection is enabled for this app on this device.

setConsent

fun setConsent(
    consentSettings: (Mutable)Map<FirebaseAnalytics.ConsentType!, FirebaseAnalytics.ConsentStatus!>
): Unit

Sets the applicable end user consent state (e.g., for device identifiers) for this app on this device. Use the consent map to specify individual consent type values. Settings are persisted across app sessions.

Parameters
consentSettings: (Mutable)Map<FirebaseAnalytics.ConsentType!, FirebaseAnalytics.ConsentStatus!>

The map of consent types. Supported consent type keys are AD_STORAGE, ANALYTICS_STORAGE, AD_USER_DATA and AD_PERSONALIZATION. Valid values are GRANTED and DENIED.

setCurrentScreen

@MainThread
@Keep
fun setCurrentScreen(
    activity: Activity,
    screenName: @Size(min = 1, max = 36) String?,
    screenClassOverride: @Size(min = 1, max = 36) String?
): Unit

Sets the current screen name, which specifies the current visual context in your app. This helps identify the areas in your app where users spend their time and how they interact with your app.

Note that screen reporting is enabled automatically and records the class name of the current Activity for you without requiring you to call this function. The class name can optionally be overridden by calling this function in the onResume callback of your Activity and specifying the screenClassOverride parameter.

If your app does not use a distinct Activity for each screen, you should call this function and specify a distinct screenName each time a new screen is presented to the user.

The name and classOverride remain in effect until the current Activity changes or a new call to setCurrentScreen is made.

This method must be called from the app's main thread.

Parameters
activity: Activity

The activity to which the screen name and class name apply.

screenName: @Size(min = 1, max = 36) String?

The name of the current screen. Set to null to clear the current screen name.

screenClassOverride: @Size(min = 1, max = 36) String?

The name of the screen class. By default this is the class name of the current Activity. Set to null to revert to the default class name.

setDefaultEventParameters

fun setDefaultEventParameters(parameters: Bundle?): Unit

Adds parameters that will be set on every event logged from the SDK, including automatic ones. The values passed in the parameters bundle will be added to the map of default event parameters. These parameters persist across app runs. They are of lower precedence than event parameters, so if an event parameter and a parameter set using this API have the same name, the value of the event parameter will be used. The same limitations on event parameters apply to default event parameters.

Parameters
parameters: Bundle?

Parameters to be added to the map of parameters added to every event. They will be added to the map of default event parameters, replacing any existing parameter with the same name. Valid parameter values are String, long, and double. Setting a key's value to null will clear that parameter. Passing in a null bundle will clear all parameters.

setSessionTimeoutDuration

fun setSessionTimeoutDuration(milliseconds: Long): Unit

Sets the duration of inactivity that terminates the current session. The default value is 1800000 (30 minutes).

Parameters
milliseconds: Long

Session timeout duration in milliseconds

setUserId

fun setUserId(id: String?): Unit

Sets the user ID property. This feature must be used in accordance with Google's Privacy Policy.

Parameters
id: String?

The user ID to ascribe to the user of this app on this device, which must be non-empty and no more than 256 characters long. Setting the ID to null removes the user ID.

setUserProperty

fun setUserProperty(
    name: @Size(min = 1, max = 24) String,
    value: @Size(max = 36) String?
): Unit

Sets a user property to a given value. Up to 25 user property names are supported. Once set, user property values persist throughout the app lifecycle and across sessions.

Parameters
name: @Size(min = 1, max = 24) String

The name of the user property to set. Should contain 1 to 24 alphanumericcharacters or underscores and must start with an alphabeticcharacter. The "firebase_", "google_" and "ga_" prefixes are reserved and should not be used for user property names.

value: @Size(max = 36) String?

The value of the user property. Values can be up to 36 characters long. Setting the value to null removes the user property.

Extension functions

logEvent

inline fun FirebaseAnalytics.logEvent(name: String, block: ParametersBuilder.() -> Unit): Unit

Fluent version of FirebaseAnalytics.logEvent.

Example use:

Firebase.analytics.logEvent("myEvent") {
param(Params.VALUE, 3.99)
param(Params.CURRENCY, "USD")
}

logEvent

inline fun FirebaseAnalytics.logEvent(name: String, block: ParametersBuilder.() -> Unit): Unit

Fluent version of FirebaseAnalytics.logEvent.

Example use:

Firebase.analytics.logEvent("myEvent") {
param(Params.VALUE, 3.99)
param(Params.CURRENCY, "USD")
}

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-analytics-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.,

setConsent

inline fun FirebaseAnalytics.setConsent(crossinline block: ConsentBuilder.() -> Unit): Unit

Fluent version of FirebaseAnalytics.setConsent.

Example use:

Firebase.analytics.setConsent {
adStorage = ConsentStatus.GRANTED
analyticsStorage = ConsentStatus.GRANTED
adUserData = ConsentStatus.GRANTED
adPersonalization = ConsentStatus.GRANTED
}

setConsent

inline fun FirebaseAnalytics.setConsent(crossinline block: ConsentBuilder.() -> Unit): Unit

Fluent version of FirebaseAnalytics.setConsent.

Example use:

Firebase.analytics.setConsent {
adStorage = ConsentStatus.GRANTED
analyticsStorage = ConsentStatus.GRANTED
}

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-analytics-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.,