All Collections
Share & Embed
Widgets Embed/iframe APIs (Advanced)
Widgets Embed/iframe APIs (Advanced)

This article explain APIs for controlling widget embeds programmatically with JavaScript

Dima Mjakotnyj avatar
Written by Dima Mjakotnyj
Updated over a week ago

Opinion Stage widget embeds (general embed or iframe) send different events (e.g., the widget's height change) to the host using the javascript window.postMessage facility.

The event messages originate from "https://www.opinionstage.com" and are serialized as JSON strings. The event data JSON has a mandatory "name" key (string) that signals the event type.

IMPORTANT: the widgets send multiple events to their JavaScript loader code for different purposes. Events that do not have the "name" key are internal and may be subject to change in the future. Please do not rely on such events. Make sure to use the latest general embed or iframe code when implementing this functionality.

To subscribe to the public events API, use the following code:

window.addEventListener('message', function (event) {
if (event.origin !== 'https://www.opinionstage.com') { return }

var payload

try {
payload = JSON.parse(event.data)
} catch(e) {
(console.error || console.log)('failed parsing OpinionStage event data:', e)
return
}

if ( payload.name === 'EVENT NAME, see documentation below for exact names' ) {
console.log('received OpinionStage event:', payload)
}
}, false)

Height change event (name: "opinionstage:v1:widget:height:change")

The height change event is posted each time the widget's IFRAME height is changed due to a user action. The event is not posted when the height doesn't change (even if the user interacted with the widget).

Example payload:

{
name: "opinionstage:v1:widget:height:change",
height: {
previous: 200,
current: 590,
},
widgetIframe: "(string)",
widgetLoaderPlaceholder: "(string)",
}

Payload data explained:

  • "payload.name" - mandatory event name (for height change event it's always "opinionstage:v1:widget:height:change")

  • "payload.height.current" - the current height of the widget's IFRAME tag (can be null on the first load)

  • "payload.height.previous" - the previous height of the widget IFRAME tag

  • "payload.widgetIframe" - CSS selector of the widget IFRAME tag

  • "payload.widgetLoaderPlaceholder" - CSS selector of the widget placeholder DIV tag (this DIV tag is displayed in the widget JavaScript embed code and is absent when the widget is embedded with the iframe code)

NOTE: Please do not rely on the exact values of the CSS selectors mentioned above.

The exact values are subject to change; please always use values from payload variables.

Example usage with jQuery:

window.addEventListener('message', function (event) {
if (event.origin !== 'https://www.opinionstage.com') { return }

var payload

try {
payload = JSON.parse(event.data)
} catch(e) {
(console.error || console.log)('failed parsing OpinionStage event data:', e)
return
}

if ( payload.name === 'opinionstage:v1:widget:height:change' ) {
console.log('OpinionStage widget height change')
$(payload.widgetIframe).height(payload.height.current)
}
}, false)

Answer click event

The click event is posted each time user clicks on the widget answer.

Example payload:

{
name: "opinionstage:v1:widget:answer:click",
widgetIframe: "(string)",
widgetLoaderPlaceholder: "(string)",
}

Example usage with jQuery:

window.addEventListener('message', function (event) {
if (event.origin !== 'https://www.opinionstage.com') { return }

var payload

try {
payload = JSON.parse(event.data)
} catch(e) {
(console.error || console.log)('failed parsing OpinionStage event data:', e)
return
}

if ( payload.name === 'opinionstage:v1:widget:answer:click' ) {
console.log('OpinionStage widget answer click')
// update ads code can be here
}
}, false)
Did this answer your question?