Recommended events

These events let you measure additional features and behavior and generate more useful reports in Google Analytics 4. Because these events require additional context to be meaningful, they are not sent automatically. Use this document to see the required and optional parameters for each event.

Google tag Tag Manager Firebase

add_payment_info

This event signifies a user has submitted their payment information in an ecommerce checkout process.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the event. Event-level and item-level coupon parameters are independent.
payment_type	string	No	Credit Card	The chosen method of payment.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: add_payment_info
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Value - ecommerce.value
• Ecommerce Currency - ecommerce.currency
• Ecommerce Coupon - ecommerce.coupon
• Ecommerce Payment Type - ecommerce.payment_type
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• value - {{Ecommerce Value}}
• currency - {{Ecommerce Currency}}
• coupon - {{Ecommerce Coupon}}
• payment_type - {{Ecommerce Payment Type}}
• Trigger: event equals add_payment_info

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: add_payment_info
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "add_payment_info",
  ecommerce: {
    currency: "USD",
    value: 7.77,
    coupon: "SUMMER_FUN",
    payment_type: "Credit Card",
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

add_shipping_info

This event signifies a user has submitted their shipping information in an ecommerce checkout process.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the event. Event-level and item-level coupon parameters are independent.
shipping_tier	string	No	Ground	The shipping tier (e.g. Ground, Air, Next-day) selected for delivery of the purchased item.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: add_shipping_info
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Value - ecommerce.value
• Ecommerce Currency - ecommerce.currency
• Ecommerce Coupon - ecommerce.coupon
• Ecommerce Shipping Tier - ecommerce.shipping_tier
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• value - {{Ecommerce Value}}
• currency - {{Ecommerce Currency}}
• coupon - {{Ecommerce Coupon}}
• shipping_tier - {{Ecommerce Shipping Tier}}
• Trigger: event equals add_shipping_info

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: add_shipping_info
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "add_shipping_info",
  ecommerce: {
    currency: "USD",
    value: 7.77,
    coupon: "SUMMER_FUN",
    shipping_tier: "Ground",
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

add_to_cart

This event signifies that an item was added to a cart for purchase.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: add_to_cart
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Value - ecommerce.value
• Ecommerce Currency - ecommerce.currency
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• value - {{Ecommerce Value}}
• currency - {{Ecommerce Currency}}
• Trigger: event equals add_to_cart

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: add_to_cart
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "add_to_cart",
  ecommerce: {
    currency: "USD",
    value: 7.77,
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

add_to_wishlist

The event signifies that an item was added to a wishlist. Use this event to identify popular gift items in your app.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: add_to_wishlist
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Value - ecommerce.value
• Ecommerce Currency - ecommerce.currency
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• value - {{Ecommerce Value}}
• currency - {{Ecommerce Currency}}
• Trigger: event equals add_to_wishlist

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: add_to_wishlist
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "add_to_wishlist",
  ecommerce: {
    currency: "USD",
    value: 7.77,
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

begin_checkout

This event signifies that a user has begun a checkout.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the event. Event-level and item-level coupon parameters are independent.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: begin_checkout
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Value - ecommerce.value
• Ecommerce Currency - ecommerce.currency
• Ecommerce Coupon - ecommerce.coupon
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• value - {{Ecommerce Value}}
• currency - {{Ecommerce Currency}}
• coupon - {{Ecommerce Coupon}}
• Trigger: event equals begin_checkout

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: begin_checkout
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "begin_checkout",
  ecommerce: {
    currency: "USD",
    value: 7.77,
    coupon: "SUMMER_FUN",
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

earn_virtual_currency

This event measures when a user is awarded virtual currency in a game. Log this along with spend_virtual_currency to better understand your virtual economy.

Parameters

Name	Type	Required	Example value	Description
virtual_currency_name	string	No	Gems	The name of the virtual currency.
value	number	No	5	The value of the virtual currency.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: earn_virtual_currency
• Event Parameters (Parameter Name - Value):
• virtual_currency_name - Gems
• value - 5
• Trigger the event when someone is awarded virtual currency

generate_lead

This event measures when a lead has been generated (for example, through a form). Log this to understand the effectiveness of your marketing campaigns and how many customers re-engage with your business after remarketing to the customers.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: generate_lead
• Event Parameters (Parameter Name - Value):
• currency - USD
• value - 99.99
• Trigger the event when a lead has been generated

join_group

Log this event when a user joins a group such as a guild, team, or family. Use this event to analyze how popular certain groups or social features are.

Parameters

Name	Type	Required	Example value	Description
group_id	string	No	G_12345	The ID of the group.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: join_group
• Event Parameters (Parameter Name - Value):
• group_id - G_12345
• Trigger the event when a user joins a group

level_end

This event signifies that a player has reached the end of a level in a game.

Parameters

Name	Type	Required	Example value	Description
level_name	string	No	The journey begins...	The name of the level.
success	boolean	No	true	Set to true if the level was completed successfully.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: level_end
• Event Parameters (Parameter Name - Value):
• level_name - The journey begins...
• success - true
• Trigger when a player has reached the end of a level (e.g., the level confirmation page)

level_start

This event signifies that a player has started a level in a game.

Parameters

Name	Type	Required	Example value	Description
level_name	string	No	The journey begins...	The name of the level.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: level_start
• Event Parameters (Parameter Name - Value):
• level_name - The journey begins...
• Trigger when someone starts a new level (e.g., the level start page)

level_up

This event signifies that a player has leveled up in a game. Use it to gauge the level distribution of your user base and identify levels that are difficult to complete.

Parameters

Name	Type	Required	Example value	Description
level	number	No	5	The level of the character.
character	string	No	Player 1	The character that leveled up.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: level_up
• Event Parameters (Parameter Name - Value):
• level - 5
• character - Player 1
• Trigger when a player has leveled up

login

Send this event to signify that a user has logged in to your website or app.

Parameters

Name	Type	Required	Example value	Description
method	string	No	Google	The method used to login.

Example

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: login
• Event Parameters (Parameter Name - Value):
• method - Google
• Trigger when a user has logged in

post_score

Send this event when the user posts a score. Use this event to understand how users are performing in your game and correlate high scores with audiences or behaviors.

Parameters

Name	Type	Required	Example value	Description
score	number	Yes	10000	The score to post.
level	number	No	5	The level for the score.
character	string	No	Player 1	The character that achieved the score.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: post_score
• Event Parameters (Parameter Name - Value):
• score - 10000
• level - 5
• character - Player 1
• Trigger when the user posts a score

purchase

This event signifies when one or more items is purchased by a user.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
transaction_id	string	Yes	T_12345	The unique identifier of a transaction. The transaction_id parameter helps you avoid getting duplicate events for a purchase.
value	number	Yes*	12.21	The monetary value of the event. * value is required for meaningful reporting and to populate the purchasers predictive audience. * currency is required if you set value.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the event. Event-level and item-level coupon parameters are independent.
shipping	number	No	3.33	Shipping cost associated with a transaction.
tax	number	No	1.11	Tax cost associated with a transaction.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: purchase
• Ecommerce Items - ecommerce.items
• Ecommerce Transaction ID - ecommerce.transaction_id
• Ecommerce Value - ecommerce.value
• Ecommerce Tax - ecommerce.tax
• Ecommerce Shipping - ecommerce.shipping
• Ecommerce Currency - ecommerce.currency
• Ecommerce Coupon - ecommerce.coupon
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• transaction_id - {{Ecommerce Transaction ID}}
• value - {{Ecommerce Value}}
• tax - {{Ecommerce Tax}}
• shipping - {{Ecommerce Shipping}}
• currency - {{Ecommerce Currency}}
• coupon - {{Ecommerce Coupon}}
• Trigger: event equals purchase

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: purchase
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "purchase",
  ecommerce: {
      transaction_id: "T_12345",
      value: 25.42,
      tax: 4.90,
      shipping: 5.99,
      currency: "USD",
      coupon: "SUMMER_SALE",
      items: [
       {
        item_id: "SKU_12345",
        item_name: "Stan and Friends Tee",
        affiliation: "Google Merchandise Store",
        coupon: "SUMMER_FUN",
        discount: 2.22,
        index: 0,
        item_brand: "Google",
        item_category: "Apparel",
        item_category2: "Adult",
        item_category3: "Shirts",
        item_category4: "Crew",
        item_category5: "Short sleeve",
        item_list_id: "related_products",
        item_list_name: "Related Products",
        item_variant: "green",
        location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
        price: 9.99,
        quantity: 1
      },
      {
        item_id: "SKU_12346",
        item_name: "Google Grey Women's Tee",
        affiliation: "Google Merchandise Store",
        coupon: "SUMMER_FUN",
        discount: 3.33,
        index: 1,
        item_brand: "Google",
        item_category: "Apparel",
        item_category2: "Adult",
        item_category3: "Shirts",
        item_category4: "Crew",
        item_category5: "Short sleeve",
        item_list_id: "related_products",
        item_list_name: "Related Products",
        item_variant: "gray",
        location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
        price: 20.99,
        promotion_id: "P_12345",
        promotion_name: "Summer Sale",
        quantity: 1
      }]
  }
});

refund

This event signifies when one or more items is refunded to a user.

Note: We recommend that you include item information in your refund event to see item-level refund metrics in Analytics.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
transaction_id	string	Yes	T_12345	The unique identifier of a transaction.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the event. Event-level and item-level coupon parameters are independent.
shipping	number	No	3.33	Shipping cost associated with a transaction.
tax	number	No	1.11	Tax cost associated with a transaction.
items	Array<Item>	No*		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: refund
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Transaction ID - ecommerce.transaction_id
• Ecommerce Value - ecommerce.value
• Ecommerce Tax - ecommerce.tax
• Ecommerce Shipping - ecommerce.shipping
• Ecommerce Currency - ecommerce.currency
• Ecommerce Coupon - ecommerce.coupon
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• transaction_id - {{Ecommerce Transaction ID}}
• value - {{Ecommerce Value}}
• tax - {{Ecommerce Tax}}
• shipping - {{Ecommerce Shipping}}
• currency - {{Ecommerce Currency}}
• coupon - {{Ecommerce Coupon}}
• Trigger: event equals refund

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: refund
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "refund",
  ecommerce: {
    currency: "USD",
    transaction_id: "T_12345", // Transaction ID. Required for purchases and refunds.
    value: 12.21,
    coupon: "SUMMER_FUN",
    shipping: 3.33,
    tax: 1.11,
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

remove_from_cart

This event signifies that an item was removed from a cart.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: remove_from_cart
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Value - ecommerce.value
• Ecommerce Currency - ecommerce.currency
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• value - {{Ecommerce Value}}
• currency - {{Ecommerce Currency}}
• Trigger: event equals remove_from_cart

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: remove_from_cart
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "remove_from_cart",
  ecommerce: {
    currency: "USD",
    value: 7.77,
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

search

Log this event to indicate when the user has performed a search. You can use this event to identify what users are searching for on your website or app. For example, you could send this event when a user views a search results page after performing a search.

Parameters

Name	Type	Required	Example value	Description
search_term	string	Yes	t-shirts	The term that was searched for.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: search
• Event Parameters (Parameter Name - Value):
• search_term - t-shirts
• Trigger when a user searches on your website

select_content

This event signifies that a user has selected some content of a certain type. This event can help you identify popular content and categories of content on your website or app.

Parameters

Name	Type	Required	Example value	Description
content_type	string	No	product	The type of selected content.
content_id	string	No	C_12345	An identifier for the content that was selected.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: select_content
• Event Parameters (Parameter Name - Value):
• content_type - product
• content_id - C_12345
• Trigger: event equals select_content

select_item

This event signifies an item was selected from a list.

Parameters

Name	Type	Required	Example value	Description
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. Ignored if set at the item-level.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. Ignored if set at the item-level.
items	Array<Item>	Yes*		The items for the event. * The items array is expected to have a single element, representing the selected item. If multiple elements are provided, only the first element in items will be used.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: select_item
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Item List ID - ecommerce.item_list_id
• Ecommerce Item List Name - ecommerce.item_list_name
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• item_list_id - {{Ecommerce Item List ID}}
• item_list_name - {{Ecommerce Item List Name}}
• Trigger: event equals select_item

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: select_item
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "select_item",
  ecommerce: {
    item_list_id: "related_products",
    item_list_name: "Related products",
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

select_promotion

This event signifies a promotion was selected from a list.

Parameters

Name	Type	Required	Example value	Description
creative_name	string	No	summer_banner2	The name of the promotional creative. Ignored if set at the item-level.
creative_slot	string	No	featured_app_1	The name of the promotional creative slot associated with the event. Ignored if set at the item-level.
promotion_id	string	No	P_12345	The ID of the promotion associated with the event. Ignored if set at the item-level.
promotion_name	string	No	Summer Sale	The name of the promotion associated with the event. Ignored if set at the item-level.
items	Array<Item>	No		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
creative_name	string	No	summer_banner2	The name of the promotional creative. If set, event-level creative_name is ignored. If not set, event-level creative_name is used, if present.
creative_slot	string	No	featured_app_1	The name of the promotional creative slot associated with the item. If set, event-level creative_slot is ignored. If not set, event-level creative_slot is used, if present.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
promotion_id	string	No	P_12345	The ID of the promotion associated with the item. If set, event-level promotion_id is ignored. If not set, event-level promotion_id is used, if present.
promotion_name	string	No	Summer Sale	The name of the promotion associated with the item. If set, event-level promotion_name is ignored. If not set, event-level promotion_name is used, if present.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Creative Name - ecommerce.creative_name
• Ecommerce Creative Slot - ecommerce.creative_slot
• Ecommerce Promotion ID - ecommerce.promotion_id
• Ecommerce Promotion Name - ecommerce.promotion_name
• Ecommerce Items - ecommerce.items
• Event Parameters (Parameter Name - Value):
• creative_name - {{Ecommerce Creative Name}}
• creative_slot - {{Ecommerce Creative Slot}}
• promotion_id - {{Ecommerce Promotion ID}}
• promotion_name - {{Ecommerce Promotion Name}}
• items - {{Ecommerce Items}}
• Variable Type: data layer Variable - 'ecommerce.items'
• Trigger: event equals select_promotion

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: select_promotion
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "select_promotion",
  ecommerce: {
    creative_name: "Summer Banner",
    creative_slot: "featured_app_1",
    promotion_id: "P_12345",
    promotion_name: "Summer Sale",
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

share

Use this event when a user has shared content.

Parameters

Name	Type	Required	Example value	Description
method	string	No	Twitter	The method in which the content is shared.
content_type	string	No	image	The type of shared content.
item_id	string	No	C_12345	The ID of the shared content.

Example

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: share
• Event Parameters (Parameter Name - Value):
• method - Twitter
• content_type - image
• item_id - C_12345
• Trigger when a user has shared content

sign_up

This event indicates that a user has signed up for an account. Use this event to understand the different behaviors of logged in and logged out users.

Parameters

Name	Type	Required	Example value	Description
method	string	No	Google	The method used for sign up.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: sign_up
• Event Parameters (Parameter Name - Value):
• method - Google
• Trigger when a user has signed up for an account

spend_virtual_currency

This event measures the sale of virtual goods in your app and helps you identify which virtual goods are the most popular.

Parameters

Name	Type	Required	Example value	Description
value	number	Yes	5	The value of the virtual currency.
virtual_currency_name	string	Yes	Gems	The name of the virtual currency.
item_name	string	No	Starter Boost	The name of the item the virtual currency is being used for.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: spend_virtual_currency
• Event Parameters (Parameter Name - Value):
• value - 5
• virtual_currency_name - Gems
• item_name - Starter Boost
• Trigger when someone purchases a virtual good

tutorial_begin

This event signifies the start of the on-boarding process. Use this in a funnel with tutorial_complete to understand how many users complete the tutorial.

Parameters

There are no parameters for this event.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: tutorial_begin
• Trigger when someone begins the on-boarding process

tutorial_complete

This event signifies the user's completion of your on-boarding process. Use this in a funnel with tutorial_begin to understand how many users complete the tutorial.

Parameters

No parameters are suggested for this event.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: tutorial_complete
• Trigger when someone completes the on-boarding process

unlock_achievement

Log this event when the user has unlocked an achievement. This event can help you understand how users are experiencing your game.

Parameters

Name	Type	Required	Example value	Description
achievement_id	string	Yes	A_12345	The id of the achievement that was unlocked.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: unlock_achievement
• Event Parameters (Parameter Name - Value):
• achievement_id - A_12345
• Trigger when a user has unlocked an achievement

view_cart

This event signifies that a user viewed their cart.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: view_cart
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Value - ecommerce.value
• Ecommerce Currency - ecommerce.currency
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• value - {{Ecommerce Value}}
• currency - {{Ecommerce Currency}}
• Trigger: event equals view_cart

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: view_cart
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "view_cart",
  ecommerce: {
    currency: "USD",
    value: 7.77,
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

view_item

This event signifies that some content was shown to the user. Use this event to discover the most popular items viewed.

Parameters

Name	Type	Required	Example value	Description
currency	string	Yes*	USD	Currency of the items associated with the event, in 3-letter ISO 4217 format. * If you set value then currency is required for revenue metrics to be computed accurately.
value	number	Yes*	7.77	The monetary value of the event. * value is typically required for meaningful reporting. If you mark the event as a conversion then it's recommended you set value. * currency is required if you set value.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: view_item
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Value - ecommerce.value
• Ecommerce Currency - ecommerce.currency
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• value - {{Ecommerce Value}}
• currency - {{Ecommerce Currency}}
• Trigger: event equals view_item

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: view_item
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "view_item",
  ecommerce: {
    currency: "USD",
    value: 7.77,
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});

view_item_list

Log this event when the user has been presented with a list of items of a certain category.

Parameters

Name	Type	Required	Example value	Description
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. Ignored if set at the item-level.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. Ignored if set at the item-level.
items	Array<Item>	Yes		The items for the event.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: view_item_list
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Items - ecommerce.items
• Ecommerce Item List ID - ecommerce.item_list_id
• Ecommerce Item List Name - ecommerce.item_list_name
• Event Parameters (Parameter Name - Value):
• items - {{Ecommerce Items}}
• item_list_id - {{Ecommerce Item List ID}}
• item_list_name - {{Ecommerce Item List Name}}
• Trigger: event equals view_item_list

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: view_item_list
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    item_list_id: "related_products",
    item_list_name: "Related products",
    items: [
     {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    },
    {
      item_id: "SKU_12346",
      item_name: "Google Grey Women's Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 3.33,
      index: 1,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "gray",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 20.99,
      promotion_id: "P_12345",
      promotion_name: "Summer Sale",
      quantity: 1
    }]
  }
});

view_promotion

This event signifies a promotion was viewed from a list.

Parameters

Name	Type	Required	Example value	Description
creative_name	string	No	summer_banner2	The name of the promotional creative. Ignored if set at the item-level.
creative_slot	string	No	featured_app_1	The name of the promotional creative slot associated with the event. Ignored if set at the item-level.
promotion_id	string	No	P_12345	The ID of the promotion associated with the event. Ignored if set at the item-level.
promotion_name	string	No	Summer Sale	The name of the promotion associated with the event. Ignored if set at the item-level.
items	Array<Item>	Yes*		The items for the event. * The items array is expected to have a single element, representing the item associated with the promotion. If multiple elements are provided, only the first element in items will be used.

Item parameters

Name	Type	Required	Example value	Description
item_id	string	Yes*	SKU_12345	The ID of the item. *One of item_id or item_name is required.
item_name	string	Yes*	Stan and Friends Tee	The name of the item. *One of item_id or item_name is required.
affiliation	string	No	Google Store	A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope.
coupon	string	No	SUMMER_FUN	The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent.
creative_name	string	No	summer_banner2	The name of the promotional creative. If set, event-level creative_name is ignored. If not set, event-level creative_name is used, if present.
creative_slot	string	No	featured_app_1	The name of the promotional creative slot associated with the item. If set, event-level creative_slot is ignored. If not set, event-level creative_slot is used, if present.
discount	number	No	2.22	The monetary discount value associated with the item.
index	number	No	5	The index/position of the item in a list.
item_brand	string	No	Google	The brand of the item.
item_category	string	No	Apparel	The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2	string	No	Adult	The second category hierarchy or additional taxonomy for the item.
item_category3	string	No	Shirts	The third category hierarchy or additional taxonomy for the item.
item_category4	string	No	Crew	The fourth category hierarchy or additional taxonomy for the item.
item_category5	string	No	Short sleeve	The fifth category hierarchy or additional taxonomy for the item.
item_list_id	string	No	related_products	The ID of the list in which the item was presented to the user. If set, event-level item_list_id is ignored. If not set, event-level item_list_id is used, if present.
item_list_name	string	No	Related products	The name of the list in which the item was presented to the user. If set, event-level item_list_name is ignored. If not set, event-level item_list_name is used, if present.
item_variant	string	No	green	The item variant or unique code or description for additional item details/options.
location_id	string	No	ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco)	The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: `location id` is only available at the item-scope.
price	number	No	9.99	The monetary price of the item, in units of the specified currency parameter.
promotion_id	string	No	P_12345	The ID of the promotion associated with the item. If set, event-level promotion_id is ignored. If not set, event-level promotion_id is used, if present.
promotion_name	string	No	Summer Sale	The name of the promotion associated with the item. If set, event-level promotion_name is ignored. If not set, event-level promotion_name is used, if present.
quantity	number	No	1	Item quantity. If not set, quantity is set to 1.

In addition to the prescribed parameters, you can include up to 27 custom parameters in the items array.

Example

The following example is for Tag Manager implementations:

Show me the tag configuration

Tag configuration:

• Tag type: GA4 Event
• Event Name: view_promotion
• Data Layer Variables (Name - Data Layer Variable Name):
• Ecommerce Creative Name - ecommerce.creative_name
• Ecommerce Creative Slot - ecommerce.creative_slot
• Ecommerce Promotion ID - ecommerce.promotion_id
• Ecommerce Promotion Name - ecommerce.promotion_name
• Ecommerce Items - ecommerce.items
• Event Parameters (Parameter Name - Value):
• creative_name - {{Ecommerce Creative Name}}
• creative_slot - {{Ecommerce Creative Slot}}
• promotion_id - {{Ecommerce Promotion ID}}
• promotion_name - {{Ecommerce Promotion Name}}
• items - {{Ecommerce Items}}
• Trigger: event equals view_promotion

Trigger configuration:

• Trigger Type: Custom Event
• Event Name: view_promotion
• This trigger fires on: All Custom Events

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "view_promotion",
  ecommerce: {
    creative_name: "Summer Banner",
    creative_slot: "featured_app_1",
    promotion_id: "P_12345",
    promotion_name: "Summer Sale",
    items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      affiliation: "Google Merchandise Store",
      coupon: "SUMMER_FUN",
      discount: 2.22,
      index: 0,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      item_list_id: "related_products",
      item_list_name: "Related Products",
      item_variant: "green",
      location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
      price: 9.99,
      quantity: 1
    }
    ]
  }
});