Event tracking with gtag.js

This guide explains how to use gtag.js to send events to Google Analytics.

Learn more about Google Analytics Events.

Send events

To send events on a web page where the tracking snippet has been added, use the followingevent command:

gtag('event', 'event_name', {
  // Event parameters
  'parameter_1': 'value_1',
  'parameter_2': 'value_2',
  // ...

where event_name can be:

  1. A recommended event, which is associated with the recommended parameters, or,
  2. A custom event, which is associated with custom parameters.

For example, the following logs the event that the user has signed in to a Google account:

gtag('event', 'login', {'method': 'Google'});

When sending events to Google Analytics, you can specify the groups and/or properties that will receive the events. For details, see Specify groups and properties to receive the data.

Event parameters

A Google Analytics Event has the following parameters:

Parameter name Value type Required Description
event_category string No The category to which the event belongs (e.g. engagement)
event_action string Yes The type of interaction (e.g. login). The event_name is the default value for event_action.
event_label string No The additional information for the event (e.g. article (the selected content type))
value integer No A non-negative numeric value associated with the event (e.g. 42)

For a detailed description of these parameters, see Anatomy of Events.

gtag.js provides default values for a Google Analytics Event's category and label. For example, if you send the following event:

gtag('event', 'login');

the event category is engagement, the event action is login, and the event label is (not set).

To override the default Google Analytics Event category and label, provide values for the event_category and event_label parameters:

gtag('event', 'event_name', {
  'event_category': categoryName,
  'event_label': labelName

For example, the following sends a login event to Google Analytics and sets the event category to access and event label to Google:

gtag('event', 'login', {
  'event_category': 'access',
  'event_label': 'Google'

Default Google Analytics Event categories and labels

The following table lists the default event categories and default event labels. The event name is the default value for event action.

Event name Default category Default label (event parameter)
add_payment_info ecommerce  
add_to_cart ecommerce  
add_to_wishlist ecommerce  
begin_checkout ecommerce  
checkout_progress ecommerce  
generate_lead engagement  
login engagement method
purchase ecommerce  
refund ecommerce  
remove_from_cart ecommerce  
search engagement search_term
select_content engagement content_type
set_checkout_option ecommerce  
share engagement method
sign_up engagement method
view_item engagement  
view_item_list engagement  
view_promotion engagement  
view_search_results engagement search_term

gtag.js includes an event and parameter model that provides detailed reporting and allows you to benefit from future features and integrations as they become available. We recommend that you implement the following events, where appropriate, with their corresponding parameters.

Event Parameters
add_to_cart value, currency, items
add_to_wishlist value, currency, items
begin_checkout value, currency, items, coupon
checkout_progress value, currency, items, coupon
exception description, fatal
generate_lead value, currency, transaction_id
login method
purchase transaction_id, value, currency, tax, shipping, items
refund transaction_id, value, currency, tax, shipping, items
remove_from_cart value, currency, items
screen_view screen_name
search search_term
select_content content_type, items, promotions
set_checkout_option checkout_step, checkout_option
share method, content_type, content_id
sign_up method
timing_complete name, value
view_item items
view_item_list items
view_promotion promotions
view_search_results search_term

The following table lists the recommended parameters for the recommended events:

Event parameter Data type Description Example value
affiliation string The store or affiliation from which this transaction occurred 'example.com'
checkout_option string Checkout option 'VISA'
checkout_step number The step (a number) in the checkout process 2
content_type string The selected content type 'vehicle'
currency string Purchase currency in 3-letter ISO_4217 format 'USD'
items array An array of item objects
promotions array An array of promotion objects
shipping currency Shipping cost '4.95'
method string Method used for signing up 'Facebook'
tax currency Tax amount '2.45'
transaction_id string Unique ID for the transaction 'T12345'
value number Value (i.e., revenue) associated with the event 22

Item parameters

The following table lists the recommended parameters for an item in an online store:

Item parameter Data type Description Example value
id string Unique ID/SKU for the item 'P12345'
name string Item name 'Android Warhol T-Shirt'
brand string Brand of the item 'Google'
category string Item category 'Apparel/T-Shirts'
coupon string Coupon code for a purchasable item 'SUMMER_FUN'
price currency Purchase price of the item '29.20'
quantity integer Item quantity 2
variant string Item variant 'Black'
creative_name string The name of a creative used 'summer_banner_2'
creative_slot string The name of the creative slot 'banner_slot_1'
list_name string The list in which the item was presented to the user 'Search Results'
list_position integer The position of the item in the list 4
origin string The origin of the item (travel) 'LHR'
destination string The destination of the item (travel) 'CDG'
start_date string Start date in ISO 8601 Calendar date format (travel) '20150931'
end_date string End date in ISO 8601 Calendar date format (travel) '20150931'

Promotion parameters

The following table lists the recommended parameters for a promotion campaign:

Promotion parameter Data type Description Example value
id string Promotion ID 'promotion8'
name string Name of promotion '20% discount'
creative_name string The name of a creative used 'summer_banner_2'
creative_slot string The name of the creative slot 'banner_slot_1'

Custom events and parameters

In addition to the recommended events, you can use gtag.js to log a custom event with the associated parameters for any action on a web page. For example, you could log this event when a user opts into receiving your newsletter:

gtag('event', 'newsletter_opt_in', {'value': 3});

Custom parameters

You can add custom data, in the form of additional parameters, to any event (recommended or custom). For example, to track users' account types as part of the sign_up event, you could log the event as follows:

gtag('event', 'sign_up', {
  'method': 'google',
  'account_type': 'basic'

As another example, if you want to capture events from your site's video player, you could log a custom event as follows:

gtag('event', 'video_play', {
  'video_title': 'My promotional video',
  'duration': '01:32'

Send non-interactive events

In some cases you might want to send an event as a non-interaction event. To send such an event, set the non_interaction parameter to true:

gtag('event', 'video_play', {
  'video_title': 'My promotional video',
  'duration': '01:32',
  'non_interaction': true

For more information on non-interaction events and when to send them, see Non-Interaction Events.