How to use Getsitecontrol API

API: general information

First, to be able to use the Getsitecontrol widget API, you need to add the main script to your website.

Next, add the 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 allow the Getsitecontrol API to function regardless of whether the main script has finished loading.

The global gsc() function provides a base interface for almost anything you may want to achieve with the Getsitecontrol widget API.

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

You can configure your widget to appear when a site visitor performs a certain action on your website. For example, clicks a ‘contact us’ button, adds an item to the cart, etc.

Here are the steps you need to take.

1. Adjust the widget settings

Open your Getsitecontrol dashboard, find the necessary widget on the list, and click Edit.

Then, switch to the Targeting tab and find the ‘Start displaying widget’ section.

If you want this widget to appear on your site only when triggered via a button click, remove all the conditions from this section.

You’ll see the following notification: The widget won't appear on the site 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 other targeting conditions to show the widget automatically AND display it using the API when necessary.

❗Please note that when you trigger the widget programmatically, it will be shown right away, regardless of any other targeting conditions specified in the widget settings.

2. Add the code that will trigger the widget

Depending on your site logic, you can implement one of the following methods to trigger your widget:

• Add a data-getsitecontrol attribute to the necessary button (or any other element) on your website.

<button data-getsitecontrol="id=1740">
  show widget id=1740
</button>

• Add a href attribute to a link:

<a href="#getsitecontrol?id=1740">
  show widget id=1740
</a>

• Link a hash address as shown below:

/page.html#getsitecontrol?id=1740

After the page has loaded, the widget with ID 1740 will be displayed.

• Use plain JavaScript API:

gsc('show', 1740)

❗1740 is an example ID, you will need to swap it with the ID of your widget.

To find the ID, go to the list of your widgets in the dashboard. The unique ID of each widget is indicated right under the widget’s name.

How to hide widgets based on your site logic

With a similar method, you can also configure your widget to hide when a visitor performs a certain action on your website (clicks a button or link, for example).

To achieve that, use the following JavaScript code:

gsc(‘close’, 1740)

❗1740 is an example ID, you will need to swap it with the ID of your widget.

How to pass extra information about your visitors

If your website has registered users, you can attach the user's email address, username, customer ID, or any other information you possess to the data they've submitted via a form.

For example, you can pass along the logged-in visitor's email address as a visitor interacts with a widget while they navigate 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@example.com',
        name: 'John',
        subscription: 19
    })
</script>

You can add the necessary properties as new parameters.

These properties will be a part of the survey response or contact submission in the downloadable reports.

You can find the reports in the Responses section below the widget.

How to display personalized messages to website visitors

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

For this purpose, you can use the method described below:

<script>
  gsc('params', {
    first_name: 'John',
        last_name: 'Smith',
        discount: 30
  })
</script>

Once you add this snippet to your site code, you will be able to use specified variables (“first_name”, “last_name”, “discount”, etc.) in the widget content in your Getsitecontrol dashboard. Put the variables in curly brackets as shown below:

For example, if first_name is ‘John’, last_name is ‘Smith’, and discount is ‘30’, here’s how John will see this popup when visiting your website:

It’s also possible to insert such variables in the URLs assigned to buttons and in the text of your emails.

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.

First, as we described earlier in this article, make sure the code that will pass the necessary parameters to Getsitecontrol API and trigger the widget is in place on your website.

<script>
 gsc('params', {
 isPaid: ‘yes’
})
</script>

Next, open the necessary widget and switch to the Targeting tab. Find the ‘Display widget if’ section and click the +Add condition link. Switch to the Developer tab and choose API parameter from the list:

Enter your custom parameter, choose the necessary logical operator, and click Done.

You can add more parameters if necessary. Just click the +Add condition link again and repeat the procedure.

Don’t forget to save the widget using the Save & close button.

That's it! Now the widget will appear for paying users only.

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){
      console.log(data);
      // outputs { email: 'user@example.com', name: 'Alex' }
    }
  })
</script>

❗1740 is an example ID, you will need to swap it with the ID of your widget.

To find the ID, go to the list of your widgets in the dashboard. The unique ID of each widget is indicated right under the widget’s name.

The callback function accepts two arguments:

• widgetId — unique widget ID

• data — collected data dictionary

The data object will feature the content of the submitted form with the following structure:

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

The data key displayed is the field ID you can set up in the field settings in the Getsitecontrol dashboard:

If you want to send the addresses collected by the widget to a third-party application, you’ll need to add the following lines of code:

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

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

gsc('onSubmit', function (widgetId, data) {
  gtag('event', 'getsitecontrol_event', {
    'type': 'submit',
    'widget_id': widgetId
  });
});

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

It’s possible to send data about other events as well. Here are the methods to use:

• onShow — will send data to GA4 when the widget appears on a page
• onClose — will send data when a visitor closes the widget
• onOpenUrl — will send data when a visitor clicks a link on the widget
• onCopyToClipboard — will send data when a visitor copies a piece of text to the clipboard via a button click
• onShowWidget — will send data when a button click on the widget triggers another widget
• onAddToCart — will send data when a visitor adds a product to the cart via a button click
• onApplyDiscount — will send data when a visitor uses a button to apply a discount to the cart.

And that is all there is to know about the Getsitecontrol API feature. Now go explore its countless possibilities!