CitySpark Portal Analytics Events
The CitySpark Portal provides two browser CustomEvent events that allow your website to track user activity using your own analytics platform. These events work well with tools such as Google Analytics 4 (GA4), making it easy to track event detail pages and searches as virtual page views within a single-page application (SPA).
Important: Register your event listeners before the CitySpark Portal JavaScript loads, or as early as possible during your page initialization, to ensure all events are captured.
Available Analytics Events
The CitySpark Portal currently exposes two analytics events:
cityspark.details– Triggered when a visitor opens an event's detail page.cityspark.search– Triggered when a visitor changes the event search criteria.
Both events are dispatched on the browser's document object.
Event Detail Tracking (cityspark.details)
The cityspark.details event fires whenever an event has been successfully loaded into the Portal's Event Details view.
This allows your analytics platform to record an event detail page as a virtual page view.
Event Properties
The following properties may be included:
Property | Description |
name | The name of the event. |
cityState | The city and state where the event takes place. |
categoryTags | The event's categories or tags. |
start | The event start date and time. |
venue | The venue where the event is held. |
sessionViewCount | Number of times the event details page has been opened during the current Portal session. |
Session View Count
The sessionViewCount value helps identify repeated views during a user's current session.
For example:
First time opening an event → 1
Opening the same event again → 2
Opening it a third time → 3
Google Analytics 4 Example
<script>
document.addEventListener('cityspark.details', function (event) {
const details = event.detail;
const virtualPath = '/events/' + encodeURIComponent(details.name);
gtag('event', 'page_view', {
page_path: virtualPath,
page_title: details.name,
event_category: details.categoryTags || undefined,
event_label: details.venue || undefined,
city_state: details.cityState || undefined,
event_start: details.start || undefined,
session_view_count: details.sessionViewCount
});
});
This example assumes your website uses the Google Analytics gtag() function. The same event information can also be sent to other analytics providers using their own tracking APIs.
Event Search Tracking (cityspark.search)
The cityspark.search event is triggered whenever a user changes the search filters within the Portal and the search URL is updated.
This allows search activity to be recorded as virtual page views.
Event Properties
Only non-default search values are included.
Possible properties include:
Property |
search |
start |
end |
location |
page |
pick |
sparks |
virtual |
subset |
distance |
category |
view |
Category Values
If multiple categories are selected, the category property is returned as a comma-separated string.
Google Analytics 4 Example
<script>
document.addEventListener('cityspark.search', function (event) {
const query = event.detail;
const searchParams = new URLSearchParams();
Object.entries(query).forEach(function ([key, value]) {
if (value !== undefined && value !== null && value !== '') {
searchParams.set(key, String(value));
}
});
gtag('event', 'page_view', {
page_path: '/events/search?' + searchParams.toString(),
page_title: 'Event Search',
search_term: query.search || undefined,
event_category: query.category || undefined,
location: query.location || undefined,
view_type: query.view || undefined
});
});
Important Behavior
Understanding when these events fire is important for accurate analytics reporting.
Event | Trigger |
| Fired after an event has been successfully loaded into the Event Details view. |
| Fired when a user changes the search route using the Portal interface. |
Search Event Limitations
The cityspark.search event is not triggered for every Portal API request.
For example, it does not fire when:
The initial Portal URL is loaded.
Additional search results are loaded (such as "Load More" actions).
Background API requests occur without changing the search route.
Prevent Duplicate Analytics
Because the CitySpark Portal behaves as a single-page application (SPA), your analytics platform may already be configured to automatically record page views.
If you are using the cityspark.details and cityspark.search events to send virtual page views, you should avoid sending an additional automatic page view for the same route change. Doing so can result in duplicate page view counts and inflated analytics data.
Summary
The CitySpark Portal provides two built-in browser events that make it easy to integrate with Google Analytics 4 or other analytics platforms:
cityspark.detailstracks when users open event detail pages.cityspark.searchtracks when users perform searches within the Portal.Both events are dispatched on the
documentobject.Register listeners early during page initialization.
Treat these events as virtual page views within your analytics solution.
Avoid duplicate page view tracking to ensure accurate reporting.