How to use Getsitecontrol
widget API

How to use Getsitecontrol 
widget API

This is an advanced feature that requires some programming knowledge. Please note that we are unable to provide support for creating or troubleshooting custom code.

API: general information

How to display widgets based on your site logic (e.g. button clicks)

How to pass extra information about your visitors

How to display personalized messages to website visitors

How to target visitors by custom API parameters

How to use event handler callbacks

How to track pages in Single Page Apps

API: general information

First of all, to be able to use Getsitecontrol widget API, you need to make sure that you already have the main script installed on your website.

On the next step, you should add a code snippet that will define the global gsc() function. Here it is:

<script>  
  window.gsc=window.gsc||function(){
    (gsc.q=gsc.q||[]).push(arguments)
  };
</script>

Place this script as high in the code of the page as possible. This will enable you to use Getsitecontrol API regardless of whether or not the main script has finished loading.

The global gsc() function provides an interface for doing almost everything you need to do with the Getsitecontrol widget API.

How to display widgets based on your site logic (e.g. button clicks)

Your can configure your widget to be displayed when a site visitor performs a certain action on your website (for example, clicks a ‘contact me’ button, adds an item to cart, etc.).

Here are the steps you need to take:

1. Check the widget settings

Open your Getsitecontrol dashboard, find the necessary widget in the list and click Edit. Then switch to the Targeting tab. Find the Start to display the widget section.

If you want this widget only to be displayed programmatically and not to be shown on your site unless you trigger it, remove all the conditions from this section.

You’ll see the notification The widget won't appear on the website automatically but you can trigger it programmatically. Save the changes using the Save & Close button and activate the widget in your dashboard.

Alternatively, you can use the targeting conditions to show the widget automatically and display it using the API when necessary. But please note that if you trigger the widget programmatically it will be shown right away regardless of the targeting conditions specified in the widget settings.

2. Add the code that will trigger the widget

To trigger the widget, you’ll need to call the gsc function with specific parameters, as shown below:

gsc('show', 1740)

For example, you can call it in the href link:

<a href="javascript:gsc('show', 1740)">
  show widget id=1740
</a>

It’s also possible to use the onclick handler:

<button role="button" onclick="gsc('show', 1740)">
  show widget id=1740
</button>

'1740' in our examples is the widget's ID, and you will need to change it to the ID of the actual widget. To find this ID, open the list of your widgets on the dashboard. The unique ID of each widget is indicated right under the widget name.

How to pass extra information 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:

<script>
  gsc('params', {
    email: '<%= user.email %>',
    name: '<%= user.name %>',
    subscription: <%= user.subscriptionAmount %>
  })
</script>

You can add the necessary properties as new parameters.

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

How to display 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. For this purpose you can use the same method as in the paragraph above:

<script>
  gsc('params', {
    first_name: '<%= user.firstName %>',
    last_name: '<%= user.lastName %>',
    discount: <%= user.discount %>
  })
</script>

Once you add this snippet to your site code, you will be able to use the specified variables (first_name, last_name, discount, etc.) when editing widget content in your Getsitecontrol dashboard:

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 first_name is ‘John’, last_name is ‘Smith’ and discount is ‘30’ here is how John will see this Promo widget when visiting your website:

It’s possible to insert the variables not only in the copy of the widget itself, but also inside the URLs assigned to buttons, or into the text of your autoresponder messages.

How to target visitors by custom API parameters

You can use API targeting to display widgets based on certain information or properties in your web application logic. Here are the steps you need to take:

1. Add the code that will trigger the widget

Here is the method you should use:

<script>
  gsc('params', {
    email: '<%= user.email %>',
    name: '<%= user.name %>',
    subscription: <%= user.subscriptionAmount %>
  })
</script>

Let's say we want to target female paid users only. We should add the following method call somewhere in our template code to pass the necessary parameters to Getsitecontrol API.

<script>
  gsc('params', {
    isPaid: <%= user.isPaid %>,
    sex: '<%= user.sex %>',
  })
</script>

<%= ...%> is an example of a template tag.

This code will set two parameters for widget targeting: isPaid and sex.

2. Change the widget settings

Then we need to configure the widget to understand these parameters.

Open the necessary widget and switch to the Targeting tab. Find the Show widget to visitors if section and click the +Add filter link. Choose API parameter from the dropdown list.

Enter your custom parameters one by one. Once the first one is entered, click the Done link. Further parameters can be added with the +Add filter link.

In our example user.isPaid is a number value (0 or 1) and user.sex can be male or female.

When entering your parameters you can choose the necessary logical operator.

You can also use the AND and OR operators to combine two or more filters into a compound condition.

Don’t forget to save the widget using the Save & close button. That's it! Now this widget will now be shown to female paid users only.

3. Use segments for fine-tuning

To combine various API targeting parameters, you can use extra segments. They come in handy when you need to show your widget to a very particular audience.

Click the +Add segment link to add a segment.

When adding segments, you can use AND and OR operators as well:

In the example below, we target paid users or those who have a payment method added to their account.

Then we add a segment to show the widget only to those users who have no discount coupon. Using these settings we can offer them a special discount.

How to use 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:

<script>
  gsc('onSubmit', function(widgetId, data) {
    if (widgetId === 1740){
      // data = {email: 'user@example.com', name: 'Alex'}
    }
  })
</script>

'1740' in our example is the widget's ID, and you will need to change it to the ID of the actual widget. To find this ID, open the list of your widgets on the dashboard. The unique ID of each widget is indicated right under the widget name.

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:

{
 email: 'user@example.com', 
 name: 'Alex'
}

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

gsc('onSubmit', function (widgetId, data) {
    if (data && data.email) {
     someThirdPartyProvider.registerEmail(data.email);
    }
});

You can also use this to track the number of form submissions with Google Analytics. Here’s a code example for the contact widget:

gsc('onSubmit', function (widgetId, data) {
    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.

How to track pages in Single Page Apps

If you have a Single Page App that uses the HTML5 History API for routing (React, Angular, etc.) and want to use URL targeting for widgets, then you need to tell the widget API on which page your app is. Here is the method you should use on every route change:

<script>
  gsc('trackPage','/new-url')
</script>

This will tell widgets that the page has been changed and that the new page is /new-url.