BFG Store Locator GA4 Custom Events

Written By Zoren Lumosbog

Last updated About 1 month ago

This document outlines all custom Google Analytics 4 (GA4) events tracked in the application, including their event names and associated parameters. This will help your analytics team map custom dimensions and create reports effectively.

Locator session parameters (on every custom event)

Every event sent through the locator analytics pipeline is merged with the locator analytics context before it is sent to GA4. These parameters are present on all of the custom events listed below (values may be empty strings when not applicable).

Parameter	Type	Description
`locator_type`	string	`product` when the user is on the product store locator; `general` when on the general store locator.
`upc`	string	Active product UPC on the product locator after product data is loaded; otherwise `''`.
`sku`	string	Active product SKU on the product locator after product data is loaded; otherwise `''`.

Product locator behavior: When the map loads a product locator session, the app sets this context from the loaded product so map_search, store_, map_, api_*, geocode_result, data_load_error, etc. all carry the same upc and sku for that session. On the general locator, locator_type is general and upc / sku are empty.

Reporting: Register locator_type, upc, and sku as event-scoped custom dimensions in GA4 if you need them in explorations and standard reports beyond DebugView.

1. `product`

Purpose: Fires once for a product locator session after analytics is enabled and the measurement snippet has been injected. Anchors the session to the active product.

Parameters: The product locator session parameters described above (locator_type, upc, sku).

When: Product locator only (locator_type = product). Not emitted for the general locator.

2. `map_search`

Purpose: Tracks user searches on the map view.

Parameters:

search_success (boolean): true if results > 0, otherwise false.
total_results (number): Count of results returned.
zero_result (boolean): true if no results returned.
selected_filters (string): JSON-encoded object of selected filters.
search_term (string): Search keyword entered by user.
refined_search_count (number): Number of times the search was refined.

Plus product locator session parameters (locator_type, upc, sku).

3. `store_impression`

Purpose: Tracks when a store is counted as an impression in the locator list/map flow.

Parameters:

store_id (string): Dealer platform id (account_id) when present; otherwise the store’s numeric id as a string.
store_name (string): Store name.

Plus product locator session parameters.

Implementation note: The app deduplicates impressions by numeric store id so the same physical store is not re-sent on every filter tick within a session.

4. `store_click`

Purpose: Tracks when a store marker is clicked.

Parameters:

store_id (string): Same semantics as store_impression.
store_name (string): Store name.

Plus product locator session parameters.

5. `store_details_view`

Purpose: Tracks when a user views the store’s details (e.g. list or panel interaction).

Parameters:

store_id (string): Same semantics as store_impression.
store_name (string): Store name.

Plus product locator session parameters.

6. `store_viewport_duration`

Purpose: Tracks how long a store’s marker stayed in the viewport timing window before a click cleared the timer.

Parameters:

store_id (string): Same semantics as store_impression.
store_name (string): Store name.
duration_seconds (number): Time (in seconds) the store marker was visible before the click, rounded.

Plus product locator session parameters.

7. `map_interaction`

Purpose: Tracks user interactions with the map.

Parameters:

interaction_type (string): Action type (e.g. zoom, pan).
latitude (number): Map center latitude.
longitude (number): Map center longitude.
zoom_level (number): Map zoom level.
zoom_result_count (number): Number of results visible at that interaction.

Plus product locator session parameters.

8. `store_distance_analysis`

Purpose: Tracks distance from the search origin to the selected store when a marker is clicked.

Parameters:

store_id (string): Same semantics as store_impression.
store_name (string): Store name.
user_latitude (number): Origin latitude used for the calculation.
user_longitude (number): Origin longitude used for the calculation.
store_latitude (number): Store latitude.
store_longitude (number): Store longitude.
distance_km (number): Great-circle distance in kilometers (two decimal places).

Plus product locator session parameters.

9. `map_filter_usage`

Purpose: Tracks usage of map filters.

Parameters:

filter_combination (string): JSON of filters applied.
filter_result_count (number): Results count with filters.
filter_engagement (number): Engagement metric (e.g. whether any results).

Plus product locator session parameters.

10. `map_control_usage`

Purpose: Tracks user actions on map controls (zoom, reset view, etc.).

Parameters:

control_name (string): Name of control used (e.g. zoom_in, zoom_out, reset_view).
control_zoom_level (number): Zoom level when the control was used.
control_zoom_result_count (number): Result count at that zoom level.

Plus product locator session parameters.

11. `geocode_result`

Purpose: Tracks geocoding / location resolution outcomes.

Parameters:

success (boolean): Whether the geocode path succeeded.
method (string): Method or channel identifier.
query (string): Query or status string associated with the attempt.

Plus product locator session parameters.

12. `api_response_time`

Purpose: Tracks API performance for locator-related requests.

Parameters:

endpoint (string): Logical name of the API endpoint.
duration_ms (number): Time taken in milliseconds.
success (boolean): Whether the call succeeded.

Plus product locator session parameters.

13. `data_load_error`

Purpose: Tracks errors during data loading.

Parameters:

error_type (string): Type/category of the error.
error_message (string): Description of the error.

Plus product locator session parameters.

14. `api_quota_error`

Purpose: Tracks quota or limit errors from external services (when used).

Parameters:

service (string): Service name.
error_message (string): Description of the error.

Plus product locator session parameters.

Notes for report creation

For each parameter you want in GA4 reports, define a Custom dimension or Custom metric in GA4 admin (event-scoped for upc, sku, locator_type, and store-related fields as needed).
Use Explorations or event name filters to separate product vs general locator behavior; use locator_type and/or upc / sku to tie map behavior to the active product on product locators.
Use GA4’s Exploration Reports or pivot-style analyses for grouped, event-specific metrics.