How to use GetSiteControl widget API

GetSiteControl offers a client-side API that controls how the widgets behave on your page. Here is what our API can help you do:

Calling API methods

Here is how a correct method call will look like:

_gscq.push(['{api-method}','{key}', '{value}']);

Add the necessary method call right after the main GetSiteControl script as in the example below:

<script>
...GetSiteControl script...
</script>

<script>
_gscq.push(['user','email', 'user.email@mail.com']); 
</script>

API use cases

Passing additional properties about your visitors

If your website has registered users, you can connect the user’s email address, username, customer ID or any other identifying string to their survey response or contact submission. For example, you can pass along the logged-in visitor’s email address as a visitor navigates through the site. Your visitor’s email address will be associated with their survey response or contact message.

Here is the method you should use:

_gscq.push(['user','{any-key}', '{any-value}']);

Code example:

_gscq.push(['user','name', '<%= user.name %>']);
_gscq.push(['user','email', '<%= user.email %>']);
_gscq.push(['user','is_paid', '<%= user.is_paid %>']);

These properties will be passed along with the response at the time the visitor submits a survey response or a contact message. These additional properties will show up in the downloadable reports, attached to the survey response or contact submission each visitor sent.

Displaying personalized messages to website visitors

You can use the user authentication data you have (name, email, gender, etc.) to create and show personalized messages while the visitor is navigating through your website.

Here is the method you should use:

_gscq.push(['template','{any-key}', '{any-value}']);

Code example:

_gscq.push(['template','first_name', '<%= user.first_name %>']);
_gscq.push(['template','last_name', '<%= user.last_name %>']);
_gscq.push(['template','discount', '30']);

Then you will be able to use the specified variables (first_name, last_name, discount, etc.) when editing widget content in your GetSiteControl dashboard:

null

Values of these variables will not be displayed in the preview window in the dashboard, they will only be displayed on the website.

Your website visitors will see a personalized message with their name and the discount you have specified. For example, if user.first_name is ‘John’, user.last_name is ‘Smith’ and discount is ‘30’ here is how John will see this Promo widget when visiting your website:

null

Using event handler callbacks

You can register your own JavaScript functions as callbacks when website visitors submit data via a survey, contact or subscribe widget.

Here is the method you should use:

_gscq.push(['callback','submit', function (widgetId, data) {
    /*Execute the following function when a survey/contact/subscribe response has been submitted*/
}]);

The callback function accepts two arguments:

  • widgetId - unique widget ID
  • data - collected data dictionary

The data object will contain the submitted form and have the following structure:

{
 "form_info": {
  "form_page": 1,
  "form_pages": 2
 },
 "form": {
  "name": [
   {
    "value": "Entered Name"
   }
  ],
  "email": [
   {
    "value": "example@eamil.com"
   }
  ]
 }
}

‘Form’ field keys will differ depending on the type of widget and the number of fields.

For example, if you want to send the addresses collected with the Subscribe widget to a third-party application you will need to add the following:

_gscq.push(['callback','submit', function (widgetId, data) {
    if (data.form && data.form.email && data.form.email.length) {
      someThirdPartyProvider.registerEmail(data.form.email[0].value);
    }
}]);

You can also use this to track the number of form submissions with Google Analytics (Contact widget):

_gscq.push(['callback','submit', function (widgetId, data) {
    //https://developers.google.com/analytics/devguides/collection/analyticsjs/events
    ga('send', 'event', 'Contact widget', 'Request');
}]);

This will send an event to Google Analytics every time someone submits a message via the Contact widget on your website.