SightMap® Metrics API

Introduction

The SightMap® Metrics API provides third-party developers a consistent event API for gathering metric data from a SightMap® IFrame which can be tightly integrated into Google Analytics or similar platforms. This functions as part of the SightMap® JavaScript IFrame API.

The web page must listen for the desired metrics events and send the wanted data to the analytics platform of your choosing. This should be configured by a web developer familiar with JavaScript.

👍
The Metrics API only exposes the metric data, so it can be made compatible with any analytics platform.

Quick Start

🏎️ For a really quick start, see our working examples at the bottom of the page 🏎️

A working example integrating the API with an example SightMap instance is below. You may insert following usage examples within this HTML document in order to explore the API.

🚧
Setting the origin value
Set the origin query parameter to the origin serving the document. The example uses http://localhost:3000, however please update the value accordingly.
If you need to start a local server, the following gist provides instructions for doing so quickly on either Mac or PC: https://gist.github.com/jgravois/5e73b56fa7756fd00b89.
For security reasons, the example must be served from an origin and will not function correctly when directly opened in a Browser.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>SightMap JavaScript IFrame API Example</title>
    <style type="text/css">
        * {
            box-sizing: border-box;
        }
        html, body {
            height: 100%;
            margin: 0;
            padding: 0;
        }
    </style>
</head>
<body>
    <!-- The API script must be included on the page -->
    <script src="https://sightmap.com/embed/api.js"></script>

    <!--
    Include the IFrame embed code. The embed URL must include `enable_api=1` and 
    provide the pages origin, the example uses `http://localhost:3000`, however
    update this accordingly. Additionally, the iframe must declare an id
    attribute, in this case it is set to `sightmap`.
    -->
    <iframe id="sightmap" src="https://sightmap.com/embed/ryzvg6mywln?enable_api=1&origin=http://localhost:3000" frameborder="0" width="100%" height="100%"></iframe>

    <script type="text/javascript">
        // Create a new embed instance, providing the IFrame id value:
        var embed = new SightMap.Embed('sightmap');

        // Usage example code goes here...
    </script>
</body>
</html>

Usage Requirements

In order to use the SightMap JavaScript IFrame API, the page must include the following script tag prior to the embed code.

<!-- The API script must be included on the page -->
<script src="https://sightmap.com/embed/api.js"></script>

The embed url must also pass parameters to enable the API and specify the web page origin. An id must also be declared, to be referenced when initializing the Embed object.

<iframe id="sightmap" src="https://sightmap.com/embed/dgow3krqp2m?enable_api=1&origin=http://localhost:3000" frameborder="0" width="100%" height="100%"></iframe>

metrics.unitMatches.impression

Fired when the SightMap application is first rendered.

{
    name: "metrics.unitMatches.impression",
    data: {
        units: [
            {
                id: "374030",
                mapId: "374030", // deprecated, use `id` instead
                unitNumber: "2-101",
                area: 1887,
                areaDisplay: "1,877 Sq. Ft.",
                price: 2315, // nullable
                priceDisplay: "$2,315", // nullable
                availableOn: "2018-09-14", // nullable
                availableOnDisplay: "Available Now", // nullable
                floor: {
                    id: "7961",
                    filterLabel: "Floor 1",
                    filterShortLabel: "1"
                },
                floorPlan: {
                    id: "25575",
                    name: "A2",
                    bedroomCount: 1,
                    bathroomCount: 1
                }
            },
            {
                id: "374030",
                mapId: "374030", // deprecated, use `id` instead
                unitNumber: "2-101",
                area: 1887,
                areaDisplay: "1,877 Sq. Ft.",
                price: 2315, // nullable
                priceDisplay: "$2,315", // nullable
                availableOn: "2018-09-14", // nullable
                availableOnDisplay: "Available Now", // nullable
                floor: {
                    id: "7961",
                    filterLabel: "Floor 1",
                    filterShortLabel: "1"
                },
                floorPlan: {
                    id: "25575",
                    name: "A2",
                    bedroomCount: 1,
                    bathroomCount: 1
                }
            }
        ]
    }
}

embed.on('metrics.unitMatches.impression', function (event) {
  console.log(event);
});

metrics.unitMatches.change

Fired when the units in the application change.

{
    name: "metrics.unitMatches.change",
    data: {
        units: [
            {
                id: "374030",
                mapId: "374030", // deprecated, use `id` instead
                unitNumber: "2-101",
                area: 1887,
                areaDisplay: "1,877 Sq. Ft.",
                price: 2315, // nullable
                priceDisplay: "$2,315", // nullable
                availableOn: "2018-09-14", // nullable
                availableOnDisplay: "Available Now", // nullable
                floor: {
                    id: "7961",
                    filterLabel: "Floor 1",
                    filterShortLabel: "1"
                },
                floorPlan: {
                    id: "25575",
                    name: "A2",
                    bedroomCount: 1,
                    bathroomCount: 1
                }
            },
            {
                id: "374030",
                mapId: "374030", // deprecated, use `id` instead
                unitNumber: "2-101",
                area: 1887,
                areaDisplay: "1,877 Sq. Ft.",
                price: 2315, // nullable
                priceDisplay: "$2,315", // nullable
                availableOn: "2018-09-14", // nullable
                availableOnDisplay: "Available Now", // nullable
                floor: {
                    id: "7961",
                    filterLabel: "Floor 1",
                    filterShortLabel: "1"
                },
                floorPlan: {
                    id: "25575",
                    name: "A2",
                    bedroomCount: 1,
                    bathroomCount: 1
                }
            }
        ]
    }
}

embed.on('metrics.unitMatches.change', function (event) {
  console.log(event);
});

metrics.unitList.impression

Fired when the unit list is first rendered.

{
    name: "metrics.unitList.impression",
    data: {
        units: [
            {
                id: "374030",
                mapId: "374030", // deprecated, use `id` instead
                unitNumber: "2-101",
                area: 1887,
                areaDisplay: "1,877 Sq. Ft.",
                price: 2315, // nullable
                priceDisplay: "$2,315", // nullable
                availableOn: "2018-09-14", // nullable
                availableOnDisplay: "Available Now", // nullable
                floor: {
                    id: "7961",
                    filterLabel: "Floor 1",
                    filterShortLabel: "1"
                },
                floorPlan: {
                    id: "25575",
                    name: "A2",
                    bedroomCount: 1,
                    bathroomCount: 1
                }
            },
            {
                id: "374030",
                mapId: "374030", // deprecated, use `id` instead
                unitNumber: "2-101",
                area: 1887,
                areaDisplay: "1,877 Sq. Ft.",
                price: 2315, // nullable
                priceDisplay: "$2,315", // nullable
                availableOn: "2018-09-14", // nullable
                availableOnDisplay: "Available Now", // nullable
                floor: {
                    id: "7961",
                    filterLabel: "Floor 1",
                    filterShortLabel: "1"
                },
                floorPlan: {
                    id: "25575",
                    name: "A2",
                    bedroomCount: 1,
                    bathroomCount: 1
                }
            }
        ]
    }
}

embed.on('metrics.unitList.impression', function (event) {
  console.log(event);
});

metrics.unitList.change

Fired when the units in the unit list change.

{
    name: "metrics.unitList.change",
    data: {
        units: [
            {
                id: "374030",
                mapId: "374030", // deprecated, use `id` instead
                unitNumber: "2-101",
                area: 1887,
                areaDisplay: "1,877 Sq. Ft.",
                price: 2315, // nullable
                priceDisplay: "$2,315", // nullable
                availableOn: "2018-09-14", // nullable
                availableOnDisplay: "Available Now", // nullable
                floor: {
                    id: "7961",
                    filterLabel: "Floor 1",
                    filterShortLabel: "1"
                },
                floorPlan: {
                    id: "25575",
                    name: "A2",
                    bedroomCount: 1,
                    bathroomCount: 1
                }
            },
            {
                id: "374030",
                mapId: "374030", // deprecated, use `id` instead
                unitNumber: "2-101",
                area: 1887,
                areaDisplay: "1,877 Sq. Ft.",
                price: 2315, // nullable
                priceDisplay: "$2,315", // nullable
                availableOn: "2018-09-14", // nullable
                availableOnDisplay: "Available Now", // nullable
                floor: {
                    id: "7961",
                    filterLabel: "Floor 1",
                    filterShortLabel: "1"
                },
                floorPlan: {
                    id: "25575",
                    name: "A2",
                    bedroomCount: 1,
                    bathroomCount: 1
                }
            }
        ]
    }
}

embed.on('metrics.unitList.change', function (event) {
  console.log(event);
});

metrics.filters.impression

Fired when the filters first render.

{
    "name": "metrics.filters.impression",
    "data": {
        "filters": [
            {
                "label": "Bedrooms",
                "name": "Bedrooms",
                "listSort": 2,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            },
            {
                "label": "Bathrooms",
                "name": "Bathrooms",
                "listSort": 3,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            },
            {
                "label": "Floor Plan",
                "name": "Floor Plan",
                "listSort": 4,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            },
            {
                "label": "Unit Price",
                "name": "Unit Price",
                "listSort": 5,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            },
            {
                "label": "Move In Date",
                "name": "Unit Move In",
                "listSort": 6,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            },
            {
                "label": "Unit Area",
                "name": "Unit Area",
                "listSort": 7,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            }
        ]
    }
}

embed.on('metrics.filters.impression', function(event) {
  console.log(event);
});

metrics.filters.change

Fired when the selected filter options change.

{
    "name": "metrics.filters.change",
    "data": {
        "filters": [
            {
                "label": "Bedrooms",
                "name": "Bedrooms",
                "listSort": 2,
                "previousSelectedOptions": [
                    {
                        "label": "Studio"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Studio"
                    }
                ]
            },
            {
                "label": "Bathrooms",
                "name": "Bathrooms",
                "listSort": 3,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            },
            {
                "label": "Floor Plan",
                "name": "Floor Plan",
                "listSort": 4,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "1 Bed 1 Bath"
                    }
                ]
            },
            {
                "label": "Unit Price",
                "name": "Unit Price",
                "listSort": 5,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            },
            {
                "label": "Move In Date",
                "name": "Unit Move In",
                "listSort": 6,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            },
            {
                "label": "Unit Area",
                "name": "Unit Area",
                "listSort": 7,
                "previousSelectedOptions": [
                    {
                        "label": "Any"
                    }
                ],
                "selectedOptions": [
                    {
                        "label": "Any"
                    }
                ]
            }
        ]
    }
}

embed.on('metrics.filters.change', function(event) {
  console.log(event);
});

metrics.unitList.unit.click

Fired when a user selects a unit from the unit list.

{
    name: "metrics.unitList.unit.click",
    data: {
        unit: {
            id: "374030",
            mapId: "374030", // deprecated, use `id` instead
            unitNumber: "2-101",
            area: 1887,
            areaDisplay: "1,877 Sq. Ft.",
            price: 2315, // nullable
            priceDisplay: "$2,315", // nullable
            availableOn: "2018-09-14", // nullable
            availableOnDisplay: "Available Now", // nullable
            floor: {
                id: "7961",
                filterLabel: "Floor 1",
                filterShortLabel: "1"
            },
            floorPlan: {
                id: "25575",
                name: "A2",
                bedroomCount: 1,
                bathroomCount: 1
            }
        }
    }
}

embed.on('metrics.unitList.unit.click', function (event) {
  console.log(event);
});

metrics.unitMap.unit.click

Fired when a user selects a unit from the unit map.

{
    name: "metrics.unitMap.unit.click",
    data: {
        unit: {
            id: "374030",
            mapId: "374030", // deprecated, use `id` instead
            unitNumber: "2-101",
            area: 1887,
            areaDisplay: "1,877 Sq. Ft.",
            price: 2315, // nullable
            priceDisplay: "$2,315", // nullable
            availableOn: "2018-09-14", // nullable
            availableOnDisplay: "Available Now", // nullable
            floor: {
                id: "7961",
                filterLabel: "Floor 1",
                filterShortLabel: "1"
            },
            floorPlan: {
                id: "25575",
                name: "A2",
                bedroomCount: 1,
                bathroomCount: 1
            }
        }
    }
}

embed.on('metrics.unitMap.unit.click', function (event) {
  console.log(event);
});

metrics.unitDetails.outbound.click

Fired when a user selects an outbound link call-to-action within the unit details modal.

{
    name: "metrics.unitDetails.outbound.click",
    data: {
        unit: {
            id: "374030",
            mapId: "374030", // deprecated, use `id` instead
            unitNumber: "2-101",
            area: 1887,
            areaDisplay: "1,877 Sq. Ft.",
            price: 2315, // nullable
            priceDisplay: "$2,315", // nullable
            availableOn: "2018-09-14", // nullable
            availableOnDisplay: "Available Now", // nullable
            floor: {
                id: "7961",
                filterLabel: "Floor 1",
                filterShortLabel: "1"
            },
            floorPlan: {
                id: "25575",
                name: "A2",
                bedroomCount: 1,
                bathroomCount: 1
            }
        },
        label: "Contact us", // nullable
        destinationUrl: "https://livemarisol.com/contact" // nullable
    }
}

embed.on('metrics.unitDetails.outbound.click', function (event) {
  console.log(event);
});

metrics.unitDetails.apply.click

Fired when a user selects the apply call-to-action within the unit details modal.

{
    name: "metrics.unitDetails.apply.click",
    data: {
        unit: {
            id: "374030",
            mapId: "374030", // deprecated, use `id` instead
            unitNumber: "2-101",
            area: 1887,
            areaDisplay: "1,877 Sq. Ft.",
            price: 2315, // nullable
            priceDisplay: "$2,315", // nullable
            availableOn: "2018-09-14", // nullable
            availableOnDisplay: "Available Now", // nullable
            floor: {
                id: "7961",
                filterLabel: "Floor 1",
                filterShortLabel: "1"
            },
            floorPlan: {
                id: "25575",
                name: "A2",
                bedroomCount: 1,
                bathroomCount: 1
            }
        },
        leaseTerm: 1, // nullable
        moveInDate: "2019-04-09",
        applyUrl: "https://livemarisol.com/apply/?SearchUrl=https%3A%2F%2Flivemarisol.com%2Fapply%2F&MoveInDate=2019-04-09&UnitId=278"
    }
}

embed.on('metrics.unitDetails.apply.click', function (event) {
  console.log(event);
});

metrics.geolocation.enable

Fired when a user selects to enable their geolocation on the SightMap.

{
	name: 'metrics.geolocation.enable',
	data: {
    location_found: true
  }
}

embed.on('metrics.geolocation.enable', function (event) {
  console.log(event);
});

Examples

The following JSFiddle demonstrates how you can listen for metrics events. In this case, the events are logged to the console. There is also a commented out code snippet at the bottom showing you can push the event data to a GTM datalayer.

📘
The Metrics API only exposes the metric data, so it can be made compatible with any analytics platform.

Google Analytics (GA4)

The following is a fully working example integrating Google Analytics (GA4) with the Metrics API. Simply find and replace the example Google tag ID G-0JXFPKZHVY with your own. You'll also need update the origin query parameter on the iframe source URL – refer to the Quick Start section above for more on this parameter.

You can also review this example working in a Code Sandbox.

📘
The Metrics API only exposes the metric data, so it can be made compatible with any analytics platform.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>
      SightMap Metrics API Example
    </title>
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-0JXFPKZHVY"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag() {
        dataLayer.push(arguments);
      }
      gtag("js", new Date());
      gtag("config", "G-0JXFPKZHVY");
    </script>
    <script src="https://sightmap.com/embed/api.js"></script>
  </head>
  <body>
    <div tabindex="0" class="sightmap-container">
      <iframe
        id="sightmap"
        src="https://sightmap.com/embed/yzvgdok1vln?enable_api=1&origin=http://localhost:3000"
        frameborder="0"
        width="100%"
        height="900px"
      >
      </iframe>
    </div>
    <script>
      //intro to metrics api to ensure Sightmap is loaded and ready for events
      document.addEventListener("DOMContentLoaded", function (event) {
        const embed = new SightMap.Embed("sightmap");
        console.log(embed);
        embed.on("ready", function () {
          console.log("SightMap is ready");
          //metrics.unitDetails.apply.click 
          embed.on("metrics.unitDetails.apply.click", function (event) {
            const unitNumber = event.data.unit.unitNumber;
            const eventName = `Apply Click - Unit ${unitNumber}`;
            gtag("event", eventName);
          });
          //metrics.unitlist.unit.click
          embed.on("metrics.unitList.unit.click", function (event) {
            const unitNumber = event.data.unit.unitNumber;
            const eventName = `Unit List Click - Unit ${unitNumber}`;
            gtag("event", eventName);
          });
          //metrics.unitmap.unit.click
          embed.on("metrics.unitMap.unit.click", function (event) {
            const unitNumber = event.data.unit.unitNumber;
            const eventName = `Unit Map Click - Unit ${unitNumber}`;
            gtag("event", eventName);
          });
          //metrics.unitmatches.impression
          embed.on("metrics.unitMatches.impression", function (event) {
            const eventName = "SightMap Unit Matches View";
            gtag("event", eventName);
          });
          //metrics.unitlist.impression
          embed.on("metrics.unitList.impression", function (event) {
            const eventName = "SightMap Unit List View";
            gtag("event", eventName);
          });
          //metrics.unitlist.change
          embed.on("metrics.unitList.change", function (event) {
            const eventName = "SightMap Unit List Change";
            gtag("event", eventName);
          });
          //metrics.unitDetails.outbound.click
          embed.on("metrics.unitDetails.outbound.click", function (event) {
            const unitNumber = event.data.unit.unitNumber;
            const ctaName = event.data.label;
            const eventName = `CTA Click - ${ctaName} - Unit ${unitNumber}`;
            gtag("event", eventName);
          });
        });
      });
    </script>
  </body>
</html>

Introduction

👍

Quick Start

🚧Setting the origin value

Usage Requirements

metrics.unitMatches.impression

metrics.unitMatches.change

metrics.unitList.impression

metrics.unitList.change

metrics.filters.impression

metrics.filters.change

metrics.unitList.unit.click

metrics.unitMap.unit.click

metrics.unitDetails.outbound.click

metrics.unitDetails.apply.click

metrics.geolocation.enable

Examples

📘

Google Analytics (GA4)

📘

🚧
Setting the origin value