<br />

You can subscribe to Places analytics events about users clicking Directions,
Call, or Website, opening Google Maps, clicking the star rating or an author
attribution, opening the photo lightbox, or switching tabs. Each event provides
a set of tags and the closest public `gmp-*` element that contains the
interaction (or `null`), from which you can read the place ID and location.

## Analytics events that are provided

The following table provides examples of analytics events that are provided by
the Places UI Kit.

| UI Interaction | `tags: Set<string>` |
|---|---|
| Directions button | `{"click", "directions", "outbound"}` |
| Open in Maps button | `{"click", "maps", "outbound"}` |
| Call button / Phone number (Overview tab) | `{"click", "call_place", "outbound"}` |
| Website button / Website (Overview tab) | `{"click", "place_website", "outbound"}` |
| Attribution link | `{"click", "attribution", "outbound"}` |
| Rating link | `{"click", "reviews", "outbound"}` |
| Legal disclosure link (`ⓘ` dialog links) | `{"click", "disclosure", "outbound"}` |
| Report link | `{"click", "report", "outbound"}` |
| Review link | `{"click", "review", "outbound"}` |
| Media / Photo link | `{"click", "media", "outbound"}` |
| Photo Lightbox opened (in-app) | `{"click", "media"}` |
| Overview tab selected (in-app) | `{"click", "overview_tab"}` |
| Reviews tab selected (in-app) | `{"click", "reviews_tab"}` |
| About tab selected (in-app) | `{"click", "about_tab"}` |
| Reviews overflow menu (`⋮`) opened (in-app) | `{"click", "reviews_menu"}` |
| Lightbox overflow menu (`⋮`) opened (in-app) | `{"click", "lightbox_menu"}` |
| Generative summary menu (`⋮`) opened (in-app) | `{"click", "generative_summary_menu"}` |
| Generative review summary menu (`⋮`) opened | `{"click", "review_summary_menu"}` |

Because new events and tags may be added over time, you can attach a generic
handler during development to log every event that is broadcast as you interact
with a component:

```javascript
const {Settings} = await google.maps.importLibrary('core');

// Log every gmp-analytics event broadcast on the page
Settings.getInstance().addEventListener('gmp-analytics', (event) => {
  console.log('Analytics event:', event);
});
```

## Subscribe to and handle analytics events

You can listen for analytics events across all Places UI Kit elements on the
page by adding a `gmp-analytics` event listener to the `google.maps.Settings`
singleton instance.

`google.maps.AnalyticsEvent` provides `event.tags` (a `Set<string>`) and
`event.element` (an `Element | null` representing the closest public `gmp-*`
element that contains the interaction, such as `gmp-place-details-compact`, or
`null` if none applies). When present, you can read the associated `Place` from
`event.element.place` (or `event.element.places` on list and search elements).

```javascript
const {Settings} = await google.maps.importLibrary('core');
const {Place} = await google.maps.importLibrary('places');

const settings = Settings.getInstance();

settings.addEventListener('gmp-analytics', (event) => {
  const {tags, element} = event; // google.maps.AnalyticsEvent
  const place = element?.place;
  const placeId = place instanceof Place ? place.id : 'none';

  // Option A: Check for specific interactions using tag strings
  if (tags.has('directions')) {
    console.log(`User requested directions for place: ${placeId}`);
  }

  if (tags.has('outbound')) {
    console.log(`User is leaving the page via: ${[...tags].sort().join(', ')}`);
  }

  // Option B: Forward every event to your analytics pipeline (for instance, Google Analytics / gtag)
  gtag('event', 'maps_javascript_api_analytics', {
    element_tag: element?.localName ?? 'none',
    tags: [...tags].sort().join(','),
    place_id: placeId,
  });
});
```

> [!NOTE]
> **Note:** The timing of the analytics callback is not guaranteed, nor is it necessarily synchronous. Analytics events may also change over time.

If your page displays multiple Places UI Kit elements, you can check `event.element` against a specific DOM element reference to determine which card instance triggered the event:

```javascript
const {Settings} = await google.maps.importLibrary('core');

const featuredCard = document.querySelector('#featured-place-card');

Settings.getInstance().addEventListener('gmp-analytics', (event) => {
  if (event.element?.contains(featuredCard) && event.tags.has('directions')) {
    console.log('Directions clicked on the featured place card:', featuredCard.place?.id);
  }
});
```