Skip to main content


Vanilla

SurveySparrow API allows you to integrate third party applications in your enterprise ecosystem and helps you to automate workflows like, sending a survey when a ticket is closed or a employee leaves the organisation.

Configuring the embed​

Once you create a embed share from SurveySparrow, you'll get a JavaScript code which can be embedded in your HTML Page. Below is an example on how to embed the JavaScript code in HTML file.

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>

<body>

    <!-- surveysparrow embed code starts here -->

    <div id="ss_survey_widget"></div>
    <script
        id="SS_SCRIPT">function sparrowLaunch(opts) { var e = "ss-widget", t = "script", a = document, r = window, l = localStorage; var s, n, c, rm = a.getElementById('SS_SCRIPT'); r.SS_WIDGET_TOKEN = "tt-ssqBcbAG2EcEBqWdZ6G2mz"; r.SS_ACCOUNT = "xyz.surveysparrow.com"; r.SS_SURVEY_NAME = "Mckinsey-Survey"; if (!a.getElementById(e) && !l.getItem('removed-ss-widget-tt-ssqBcbAG2EcEBqWdZ6G2mz')) { var S = function () { S.update(arguments) }; S.args = []; S.update = function (e) { S.args.push(e) }; r.SparrowLauncher = S; s = a.getElementsByTagName(t); c = s[s.length - 1]; n = a.createElement(t); n.type = "text/javascript"; n.async = !0; n.id = e; n.src = ["https://", "xyz.surveysparrow.com/widget/", r.SS_WIDGET_TOKEN, "?", "customParams=", JSON.stringify(opts)].join(""); c.parentNode.insertBefore(n, c); r.SS_VARIABLES = opts; rm.parentNode.removeChild(rm); } };</script>

    <!-- surveysparrow embed code ends here -->

    <script>
        window.sparrowConfig = {
            // widget configuration goes here - this is optional
        };

        //pass survey variables here
        sparrowLaunch({
            name: "John Doe",
            mail: "[email protected]"
        });
    </script>
</body>

</html>

Widget options​

SurveySparrow widget provides a set of APIs which can be used to customize the behaviour of your survey embed. Below are the supported APIs and their use.

<script>
  window.sparrowConfig = { // config goes here };
</script>
KEYDESCRIPTIONTYPE
newTabopen the redirecting URL in a new tabboolean
chatAutoStartTrigger the Widget chat automaticallyboolean
forceTriggerOpen the widget unconditionallyboolean
sparrowLangChange Survey language in the widgetISO 639-2 Language code

Below is the complete example​

<script>
  window.sparrowConfig = {
    newTab: true,
    chatAutoStart: true,
    forceTrigger: true
  };

  sparrowLaunch({
    sparrowLang: 'es',
    name: "John Doe" // custom variable
  });
</script>

Widget events​

Check if user started the survey

<script>
  window.addEventListener('message', (e) => {
    if(e && e.data && e.data.type === 'surveyLoadStarted') {
      // Survey started loading
    }
  });
</script>

Detect language changes in the survey​

You can use the below event to get notified when the user changes survey language.

<script>
  window.addEventListener('message', (e) => {
    if(e && e.data && e.data.type === 'languageChanged') {
      const { code, label } = e.data;  // language code and language label
      //Language changed
    }
  });
</script>

Detect survey completion​

<script>
  window.addEventListener('message', (e) => {
  if(e && e.data && e.data.type === 'surveyCompleted') {
    const { response, customParams } = e.data; // survey response and custom variables
    //Survey completed
    }
  });
</script>

Detect survey redirection​

To detect any redirection in the Survey, event redirectPage can be used.

<script>
  window.addEventListener('message', (e) => {
    if(e && e.data && e.data.type === 'redirectPage') {
      // Page redirected
    }
  });
</script>

Detect window close for pop-up card​

Use the removeWindow event to get notified when user closes the widget.

<script>
  window.addEventListener('message', (e) => {
    if(e && e.data && e.data.type === 'removeWindow') {
      // Window closed (pop-up card)
    }
  });
</script>