Project: /docs/reference/js/_project.yaml Book: /docs/reference/_book.yaml page_type: reference

{% comment %} DO NOT EDIT THIS FILE! This is generated by the JS SDK team, and any local changes will be overwritten. Changes should be made in the source code at https://github.com/firebase/firebase-js-sdk {% endcomment %}

analytics package

The Firebase Analytics Web SDK. This SDK does not work in a Node.js environment.

Functions

Interfaces

Type Aliases

function(app, ...)

getAnalytics(app) {:#getanalytics_cf608e1}

Returns an Analytics instance for the given app.

<b>Signature:</b>

export declare function getAnalytics(app?: FirebaseApp): Analytics;

Parameters

<b>Returns:</b>

Analytics

initializeAnalytics(app, options) {:#initializeanalytics_a68c1d7}

Returns an Analytics instance for the given app.

<b>Signature:</b>

export declare function initializeAnalytics(app: FirebaseApp, options?: AnalyticsSettings): Analytics;

Parameters

<b>Returns:</b>

Analytics

function(analyticsInstance, ...)

getGoogleAnalyticsClientId(analyticsInstance) {:#getgoogleanalyticsclientid_b0a3b5a}

Retrieves a unique Google Analytics identifier for the web client. See client_id<!-- -->.

<b>Signature:</b>

export declare function getGoogleAnalyticsClientId(analyticsInstance: Analytics): Promise<string>;

Parameters

<b>Returns:</b>

Promise<string>

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_d5f1743}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_payment_info', eventParams?: {
    coupon?: EventParams['coupon'];
    currency?: EventParams['currency'];
    items?: EventParams['items'];
    payment_type?: EventParams['payment_type'];
    value?: EventParams['value'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_507c89b}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'purchase' | 'refund', eventParams?: {
    value?: EventParams['value'];
    currency?: EventParams['currency'];
    transaction_id: EventParams['transaction_id'];
    tax?: EventParams['tax'];
    shipping?: EventParams['shipping'];
    items?: EventParams['items'];
    coupon?: EventParams['coupon'];
    affiliation?: EventParams['affiliation'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_918c505}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

See Track Screenviews<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'screen_view', eventParams?: {
    firebase_screen: EventParams['firebase_screen'];
    firebase_screen_class: EventParams['firebase_screen_class'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_97ff7c6}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'search' | 'view_search_results', eventParams?: {
    search_term?: EventParams['search_term'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_1f89527}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_content', eventParams?: {
    content_type?: EventParams['content_type'];
    item_id?: EventParams['item_id'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_5dd5dd2}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_item', eventParams?: {
    items?: EventParams['items'];
    item_list_name?: EventParams['item_list_name'];
    item_list_id?: EventParams['item_list_id'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_77bad34}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_promotion' | 'view_promotion', eventParams?: {
    items?: EventParams['items'];
    promotion_id?: EventParams['promotion_id'];
    promotion_name?: EventParams['promotion_name'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_560b592}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'set_checkout_option', eventParams?: {
    checkout_step?: EventParams['checkout_step'];
    checkout_option?: EventParams['checkout_option'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_0f60635}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'share', eventParams?: {
    method?: EventParams['method'];
    content_type?: EventParams['content_type'];
    item_id?: EventParams['item_id'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_bf98d4d}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'sign_up', eventParams?: {
    method?: EventParams['method'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_88130b6}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'timing_complete', eventParams?: {
    name: string;
    value: number;
    event_category?: string;
    event_label?: string;
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_feb40db}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_shipping_info', eventParams?: {
    coupon?: EventParams['coupon'];
    currency?: EventParams['currency'];
    items?: EventParams['items'];
    shipping_tier?: EventParams['shipping_tier'];
    value?: EventParams['value'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_cfbc3bb}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_cart' | 'view_item', eventParams?: {
    currency?: EventParams['currency'];
    items?: EventParams['items'];
    value?: EventParams['value'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_f0c3c2c}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_item_list', eventParams?: {
    items?: EventParams['items'];
    item_list_name?: EventParams['item_list_name'];
    item_list_id?: EventParams['item_list_id'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_a155179}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent<T extends string>(analyticsInstance: Analytics, eventName: CustomEventName<T>, eventParams?: {
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_c4de9a4}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_to_cart' | 'add_to_wishlist' | 'remove_from_cart', eventParams?: {
    currency?: EventParams['currency'];
    value?: EventParams['value'];
    items?: EventParams['items'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_8260753}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'begin_checkout', eventParams?: {
    currency?: EventParams['currency'];
    coupon?: EventParams['coupon'];
    value?: EventParams['value'];
    items?: EventParams['items'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_162cb02}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'checkout_progress', eventParams?: {
    currency?: EventParams['currency'];
    coupon?: EventParams['coupon'];
    value?: EventParams['value'];
    items?: EventParams['items'];
    checkout_step?: EventParams['checkout_step'];
    checkout_option?: EventParams['checkout_option'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_800159e}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

See Measure exceptions<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'exception', eventParams?: {
    description?: EventParams['description'];
    fatal?: EventParams['fatal'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_9c11aa9}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'generate_lead', eventParams?: {
    value?: EventParams['value'];
    currency?: EventParams['currency'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_1f3f282}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

List of recommended event parameters can be found in the GA4 reference documentation<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'login', eventParams?: {
    method?: EventParams['method'];
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

logEvent(analyticsInstance, eventName, eventParams, options) {:#logevent_0792e28}

Sends a Google Analytics event with given eventParams<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

See Page views<!-- -->.

<b>Signature:</b>

export declare function logEvent(analyticsInstance: Analytics, eventName: 'page_view', eventParams?: {
    page_title?: string;
    page_location?: string;
    page_path?: string;
    [key: string]: any;
}, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

setAnalyticsCollectionEnabled(analyticsInstance, enabled) {:#setanalyticscollectionenabled_494179c}

Sets whether Google Analytics collection is enabled for this app on this device. Sets global window['ga-disable-analyticsId'] = true;

<b>Signature:</b>

export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void;

Parameters

<b>Returns:</b>

void

setCurrentScreen(analyticsInstance, screenName, options) {:#setcurrentscreen_a6168fa}

Warning: This API is now obsolete.

Use with eventName as 'screen_view' and add relevant eventParams<!-- -->. See Track Screenviews<!-- -->.

Use gtag config command to set screen_name<!-- -->.

<b>Signature:</b>

export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

setUserId(analyticsInstance, id, options) {:#setuserid_86d82f6}

Use gtag config command to set user_id<!-- -->.

<b>Signature:</b>

export declare function setUserId(analyticsInstance: Analytics, id: string | null, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

setUserProperties(analyticsInstance, properties, options) {:#setuserproperties_877b6e8}

Use gtag config command to set all params specified.

<b>Signature:</b>

export declare function setUserProperties(analyticsInstance: Analytics, properties: CustomParams, options?: AnalyticsCallOptions): void;

Parameters

<b>Returns:</b>

void

function()

isSupported() {:#issupported}

This is a public static method provided to users that wraps four different checks:

1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using IndexedDB.open()<!-- -->.

<b>Signature:</b>

export declare function isSupported(): Promise<boolean>;

<b>Returns:</b>

Promise<boolean>

function(consentSettings, ...)

setConsent(consentSettings) {:#setconsent_1697027}

Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized.

Use the ConsentSettings to specify individual consent type values. By default consent types are set to "granted".

<b>Signature:</b>

export declare function setConsent(consentSettings: ConsentSettings): void;

Parameters

<b>Returns:</b>

void

function(customParams, ...)

setDefaultEventParameters(customParams) {:#setdefaulteventparameters_0682bee}

Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events.

<b>Signature:</b>

export declare function setDefaultEventParameters(customParams: CustomParams): void;

Parameters

<b>Returns:</b>

void

function(options, ...)

settings(options) {:#settings_eb37905}

Configures Firebase Analytics to use custom gtag or dataLayer names. Intended to be used if gtag.js script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the gtag function or for dataLayer<!-- -->. Must be called before calling getAnalytics() or it won't have any effect.

<b>Signature:</b>

export declare function settings(options: SettingsOptions): void;

Parameters

<b>Returns:</b>

void

ConsentStatusString

Whether a particular consent type has been granted or denied.

<b>Signature:</b>

export type ConsentStatusString = 'granted' | 'denied';

Currency

Standard Google Analytics currency type.

<b>Signature:</b>

export type Currency = string | number;

CustomEventName

Any custom event name string not in the standard list of recommended event names.

<b>Signature:</b>

export type CustomEventName<T> = T extends EventNameString ? never : T;

EventNameString

Type for standard Google Analytics event names. logEvent also accepts any custom string and interprets it as a custom event name.

<b>Signature:</b>

export type EventNameString = 'add_payment_info' | 'add_shipping_info' | 'add_to_cart' | 'add_to_wishlist' | 'begin_checkout' | 'checkout_progress' | 'exception' | 'generate_lead' | 'login' | 'page_view' | 'purchase' | 'refund' | 'remove_from_cart' | 'screen_view' | 'search' | 'select_content' | 'select_item' | 'select_promotion' | 'set_checkout_option' | 'share' | 'sign_up' | 'timing_complete' | 'view_cart' | 'view_item' | 'view_item_list' | 'view_promotion' | 'view_search_results';