Spaces® Metrics API
Intro
The Spaces Metrics API provides third-party developers a consistent event API for gathering metric data from webpages that use the Spaces® plugin, which can then be integrated into web analytics platforms like Google Analytics.
The web page must listen for the desired metrics events and send the wanted data to the analytics platform of your choosing.
The Metrics API only exposes the metric data, so it can be made compatible with any analytics platform.
This should typically be configured by a web developer familiar with JavaScript.
If your WordPress content management system (CMS) provides editable ‘Header’ and ‘Footer’ fields, you may be able to insert the code there without developer assistance.
Additional Considerations
SightMap Metrics API
Because Spaces loads SightMap natively, the Spaces Metrics API works in parallel with the SightMap® Metrics API. By implementing the Spaces Metrics API, you will be able to collect click events from throughout the Spaces search experience (units, floor plans, etc.) as well as from within the interactive SightMap.
Usage Requirements
In order to use the Spaces Metrics API, the website must satisfy the following requirements.
- Your Google tag (gtag) must be loaded on every page where you expect to collect metrics.
If the gtag is not yet present on the page(s) and if the website is not loading the script globally, reference the following. You will need to insert your gtag (replace G-XXXXXXXXXX below) and add the code snippet to the relevant webpage(s).
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
</script>
- The website must be using Spaces plugin version RC8 or later. To check what version of Spaces is in use, log in to the WordPress content management system (CMS) and navigate to Spaces > Global Settings. The title at the top lists the version of Spaces — ensure that it reads SPACES [2.0.0-rc.8] or higher.
- Need to update Spaces? Contact Engrain Support.
Events
metrics.units.change
Fired when the units in the application change, including the impression event as filters are applied.
Event Payload JSON
{
"name": "metrics.units.change",
"data": {
"units": [
{
"id": 2879722,
"unitNumber": "16103",
"area": 731,
"areaDisplay": "731 Sq. Ft.",
"price": 1976,
"priceDisplay": "$1,976",
"availableOn": "2024-08-21",
"availableOnDisplay": "Available Aug 21, 2024",
"floorPlan": {
"id": 133266,
"name": "A1",
"bedroomCount": 1,
"bathroomCount": 1
}
},
{
"id": 2879750,
"unitNumber": "18103",
"area": 731,
"areaDisplay": "731 Sq. Ft.",
"price": 1978,
"priceDisplay": "$1,978",
"availableOn": "2024-09-15",
"availableOnDisplay": "Available Sep 15, 2024",
"floorPlan": {
"id": 133266,
"name": "A1",
"bedroomCount": 1,
"bathroomCount": 1
}
}
]
}
}
metrics.unit.details.click
Fired when a user clicks a detail link from a unit card in Spaces.
Event Payload JSON
{
"name": "metrics.unit.details.click",
"data": {
"unit": {
"id": 2879722,
"unitNumber": "16103",
"area": 731,
"areaDisplay": "731 Sq. Ft.",
"price": 1976,
"priceDisplay": "$1,976",
"availableOn": "2024-08-21",
"availableOnDisplay": "Available Aug 21, 2024",
"floorPlan": {
"id": 133266,
"name": "A1",
"bedroomCount": 1,
"bathroomCount": 1
}
}
}
}
metrics.unit.apply.click
Fired when a user clicks the apply call-to-action (CTA) from a unit card or details page.
Event Payload JSON
{
"name": "metrics.unit.apply.click",
"data": {
"unit": {
"id": 2879722,
"unitNumber": "16103",
"area": 731,
"areaDisplay": "731 Sq. Ft.",
"price": 1976,
"priceDisplay": "$1,976",
"availableOn": "2024-08-21",
"availableOnDisplay": "Available Aug 21, 2024",
"floorPlan": {
"id": 133266,
"name": "A1",
"bedroomCount": 1,
"bathroomCount": 1
}
}
}
}
metrics.plans.change
Similar to the unit list change event but with floor plan data instead.
Event Payload JSON
{
"name": "metrics.plans.change",
"data": {
"plans": [
{
"id": 2879722,
"name": "A1",
"bedroomCount": 1,
"bathroomCount": 1,
"availableOn": "2024-07-08",
"price": 1976
},
{
"id": 2879722,
"name": "B2",
"bedroomCount": 2,
"bathroomCount": 2,
"availableOn": "2024-04-21",
"price": 2026
},
{
"id": 2879722,
"name": "B1",
"bedroomCount": 2,
"bathroomCount": 2,
"availableOn": "2024-06-03",
"price": 2261
},
{
"id": 2879722,
"name": "C1",
"bedroomCount": 3,
"bathroomCount": 3,
"availableOn": "2024-09-23",
"price": 2638
}
]
}
}
metrics.plan.details.click
Fired when a user clicks a detail link from a floor plan card.
Event Payload JSON
{
"name": "metrics.plan.details.click",
"data": {
"unit": {
"id": 2879722,
"name": "B1",
"bedroomCount": 3,
"bathroomCount": 3,
"availableOn": "2024-09-23",
"price": 2638
}
}
}
Quick Start
Get started with the Spaces Metrics API.
The following JS code snippet demonstrates how you can listen for metrics events. In this case, the events are logged to the console when you see console.log, and it additionally is sent to Google Tag Manager when you see gtag("event", eventName).
The first addEventListener is specifically for SightMap events that are in Spaces' ‘Map View’ tab, or wherever the SightMap is iFramed. This part does not send Spaces metrics. The second addEventListener is for Spaces metrics specifically in the ‘Plan View’ tab.
<!-- Code to be placed in HEADER -->
<script src="https://sightmap.com/embed/api.js"></script>
<!-- End of HEADER Scripts -->
<!-- Code to be placed in BODY or FOOTER -->
<script>
// intro to metrics api to ensure SightMap is loaded and ready for events
document.addEventListener("DOMContentLoaded", function (event) {
var spacesSightMap = document.getElementById('spaces_sightmap')
function initSmMetrics() {
const embed = new SightMap.Embed("spaces_sightmap")
// console.log(embed)
// Load scripts when SightMap is ready
embed.on("ready", function () {
// console.log("SightMap is ready")
// A Unit Details element is clicked
embed.on("metrics.unitDetails.apply.click", function (event) {
// console.log(event)
const unitNumber = event.data.unit.unitNumber
const eventName = `SM Apply Click - #${unitNumber}`
gtag("event", eventName)
})
//metrics.unitlist.unit.click
embed.on("metrics.unitList.unit.click", function (event) {
// console.log(event)
const unitNumber = event.data.unit.unitNumber
const eventName = `SM Unit Click - #${unitNumber}`
gtag("event", eventName)
})
//metrics.unitmap.unit.click
embed.on("metrics.unitMap.unit.click", function (event) {
// console.log(event)
const unitNumber = event.data.unit.unitNumber
const eventName = `SM Unit Click - #${unitNumber}`
gtag("event", eventName)
})
//metrics.unitmatches.impression
embed.on("metrics.unitMatches.impression", function (event) {
// console.log(event)
const eventName = "SM View"
gtag("event", eventName)
})
//metrics.unitDetails.outbound.click
embed.on("metrics.unitDetails.outbound.click", function (event) {
// console.log(event)
const unitNumber = event.data.unit.unitNumber
const ctaName = event.data.label
const eventName = `SM CTA ${ctaName} - #${unitNumber}`
gtag("event", eventName)
})
})
}
if (typeof spacesSightMap != 'null') {
initSmMetrics()
}
// After initial load, bind events to the tab changes to listen for the SightMap Embed tab to load
const spacesTabsControls = document.querySelectorAll('[data-spaces-tab-control]')
spacesTabsControls.forEach((control) => {
control.addEventListener("click", function () {
// console.log('A SPACES tab control button has been clicked.')
// Wait a moment for the SM to load before trying to test for it.
setTimeout(() => {
if (typeof spacesSightMap != 'null') {
initSmMetrics()
} else {
// Try to redefine the SightMap Element, as it wasn't set at load but may be now that the tab has changed
spacesSightMap = document.getElementById('spaces_sightmap')
if (typeof spacesSightMap != 'null') {
initSmMetrics()
}
}
}, 500)
})
})
})
// SPACES element metrics - NOTE: Requires SPACES version rc.8 or later
document.addEventListener("DOMContentLoaded", function (event) {
// Only load SPACES scripts if SPACES is present on page
if (SPACES) {
// console.log('SPACES ON PAGE')
// A Unit Details element is clicked
SPACES.on('metrics.unit.details.click', function(event) {
// console.log(event)
const unitNumber = event.data.unit.unitNumber
const eventName = `SP Unit ${unitNumber} Detail`
gtag("event", eventName)
})
// An Apply element is clicked
SPACES.on('metrics.unit.apply.click', function(event) {
// console.log(event)
const unitNumber = event.data.unit.unitNumber
const eventName = `SP Unit ${unitNumber} Apply`
gtag("event", eventName)
})
// A Floor Plan Details element is clicked
SPACES.on('metrics.plan.details.click', function(event) {
// console.log(event)
const floorPlan = event.data.unit.name
const eventName = `SP Floor Plan ${floorPlan} Detail`
gtag("event", eventName)
})
}
})
</script>
<!-- End of BODY / FOOTER scripts -->
Examples
To interact with the Spaces Metrics API, you can use the following JavaScript event listeners.
The following JavaScript code block demonstrates how you can listen for metrics events. In this case, the events are logged to the console.
if (typeof SPACES !== undefined) {
// Spaces is on the page
// Fired when the Spaces application is first rendered on unit view.
SPACES.on('metrics.units.change', function(event) {
console.log(event)
// push wanted data from event to google
})
// Fired when a user clicks into view the details of a unit
SPACES.on('metrics.unit.details.click', function(event) {
console.log(event)
// push wanted data from event to google
})
// Fired when a user clicks the apply link of a unit
SPACES.on('metrics.unit.apply.click', function(event) {
console.log(event)
// push wanted data from event to google
})
// Fired when the Spaces application is first rendered on plan view.
SPACES.on('metrics.plans.change', function(event) {
console.log(event)
// push wanted data from event to google
})
// Fired when a user clicks into view the details of a floor plan
SPACES.on('metrics.plan.details.click', function(event) {
console.log(event)
// push wanted data from event to google
})
}
To check if the Spaces app is present and the SightMap has been loaded, use the following code at the top of this JavaScript snippet. There is also a code snippet at the bottom showing how you can push the event data to Google Tag Manager.
document.addEventListener("DOMContentLoaded", function (event) {
const spacesSightMap = document.getElementById('spaces_sightmap')
const embed = new SightMap.Embed("spaces_sightmap")
embed.on("metrics.unitDetails.apply.click", function (event) {
const unitNumber = event.data.unit.unitNumber
const eventName = `SightMap Apply Click - Unit ${unitNumber}`
gtag("event", eventName)
})
})
Configure and Customize
The Spaces Metrics API is versatile by design — you can use it with any analytics platform. You can also customize it to track specific objectives.
Change events by editing the code blocks that contain the corresponding metrics event listener. For example:
Edit the formatting of the event name
Before
SPACES.on('metrics.plan.details.click', function(event) {
// console.log(event)
const floorPlan = event.data.unit.name
const eventName = `Spaces Floor Plan ${floorPlan} Detail`
gtag("event", eventName)
})
After
SPACES.on('metrics.plan.details.click', function(event) {
// console.log(event)
const floorPlan = event.data.unit.name
const eventName = `SP FP ${floorPlan} Detail`
gtag("event", eventName)
})
Add more information. If you’re observing click events on ‘Apply’ links for individual units, you can additionally append more details, such as the units’ areas
Before
SPACES.on('metrics.units.change', function(event) {
console.log(event)
const unitNumber = event.data.unit.unitNumber
const eventName = `SM Apply Click - #${unitNumber}`
gtag("event", eventName)
})
After
SPACES.on('metrics.units.change', function(event) {
console.log(event)
const unitNumber = event.data.unit.unitNumber
const areaDisplay = event.data.unit.areaDisplay
const eventName = `Spaces Apply Click - #${unitNumber} with ${areaDisplay}`
gtag("event", eventName)
})
Get Help
We’re here to help. Reach out to Engrain Support.
Updated 9 months ago