Bound - Help Center

Understanding the GSC JavaScript API and Events

Once you have enabled Bound on your website (or during the implementation and testing phase of your project), our JavaScript API provides some visibility into the active content and GSC events on a page.  You can access the following methods and properties with your browser console, or you can utilize the API to report relevant data and events back to your own systems (e.g., third party analytics tools or experiment engines).

The _gsc Object

The starting point for interaction with the API is the global _gsc object.  There are more methods and properties available in the _gsc object than will be described here, but this document will cover those that are typically most useful and relevant to Get Smart Content users.

The most important resources from that object are the api(), campaigns(), and push() methods.

 

_gsc.api()

The api() method takes no arguments, and it currently returns one object: campaigns, which is an array of active campaigns on the page.

 

 

_gsc.api().campaigns

Each campaign object in the array contains the following relevant properties:

Property Type Description Notes
campaignName string The name you assigned to this campaign in the GSC admin interface. This is the name shown in the list of campaigns for your site.
campaignPublicId string The internal durable ID assigned to the campaign by GSC. This matches an alphanumeric component of the URL you'll see when viewing or editing the campaign in the GSC admin.
content array An array of content objects displayed by this campaign.  
displayMode boolean integer Returns 1 if content is active for this campaign or 0 if conditions and rules were not met.  
ruleName string The name of the campaign rule, if any, that was triggered.  
rulePublicId string The durable ID of the active rule.  
segmentName string The name of the segment associated with the active rule that identifies and qualifies the current visitor for this campaign.  
segmentPublicId string The durable ID you will see in the URL when editing a segment in the GSC admin.  

 

GSC Event Hooks

When you enable smart content on your page, GSC automatically tracks the important metrics like impressions (how many visitors had an opportunity to view a campaign and its content?) and clicks (how many visitors interacted with GSC content?) to generate reports for A/B experiments and measuring the impact of your smart content investment.

We also provide some simple hooks via the API that allow you to perform additional actions when events occur, or to use that event data for other business purposes that you may require.  The distinction here is that you must create the scripts that receive the event notifications and then define how the associated data is handled.  GSC will continue to receive this event data for our own reporting if you choose to create event listeners, but these hooks allow you to eavesdrop on the data being generated.

Use the _gsc.push() method to add an event listener, specifying the event type and the callback function you have created the handle the event data.

_gsc.push(['_addEventListener', 'complete', 'onGSCComplete']);
_gsc.push(['_addEventListener', 'impression', 'onGSCImpression']);
_gsc.push(['_addEventListener', 'click', 'onGSCClick']);

The referenced callback function names can be anything that you define. Then, you must create those functions, each of which receives an object as its single argument.

function onGSCComplete( api ) {
    console.log( api );
}

function onGSCImpression( api ) {
    console.log( api );
}

function onGSCClick( api ) {
    console.log( api );
}

The complete event is fired when our system returns information related to the campaigns on a page after content content rules are processed; it returns an object similar to _gsc.api().  So, you can use that to do something in the DOM after all of your GSC content is added to the page.

The impression and click events are a little different; you will see one impression event that returns an object with two keys:

  • type: the event type (in this case, "impression"); and
  • campaigns: an array of all active campaigns served to the page (with associated child data described above for _gsc.api().campaigns).

There will also be a click event for each user click of content (typically a modal, banner, or fly-in) that is tracked by a GSC campaign.  It also returns an object with two keys:

  • type: the event type ("in this case, "click"); and
  • campaigns: an array of campaigns (usually just one) controlling the content that was clicked.

Note: Impression and Click events may not be fired in "Preview mode" (if you loaded the page via the Preview button in the GSC Rules list).

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request