JavaScript API

When the standard embed button codes or placeholder codes do not suit your needs, but you want to embed your project into your website, you could use the JavaScript API.

Note: This method will require you to have a basic understanding of JavaScript.

Including the Script

To use the JS API, you can embed the same script tag, which is used for the standard embed elements. This is found on the launch page of your survey.

Calling the Script

Directly making calls to the API, immediately after load, could fail if the script is not yet ready. If your calls to the API are made on the page load it is recommended that they are placed inside the ready handler.

ShoutEmbed.ready(function(){
    // Make calls to API here
});

Starting an embed

There are three types of embed, for each of these there is a different function call on the API. When this is called, it will create the embed, it will also return an instance of the EmbedController which will allow you to communicate with the instance of this form later.

First, we will look at the different calls which can be made, then at the parameters which can be supplied.   ShoutEmbed.api.popout({ formId: "###" }); ShoutEmbed.api.slideout({ formId: "###" }); ShoutEmbed.api.inline({ formId: "###", appendTo: "survey-placeholder" });

API Reference

Making calls to these functions alone will not work. We need to supply an object defining what we want it to do.

Parameter Type Description Popout Slideout Inline
formId String Defines which form we want to embed into the page. You can find this on the launch page, it is the end of the launch URL. Required Required Required
closeOnComplete Boolean Closes the form on completion, any thank you page will not be displayed. Default: FALSE x x
appendTo String or Element Element the form is to be appended to on creation. This can be the element id or the element object. Default: BODY x x Required
initialColor String Accepts a Hex color code. Used to define the color of the element which appears before the form has loaded. Default: #5E5E5E x x
direction String Which side of the page a slideout should appear on. Can be “left” or “right”. Default: “right” x
onFormLoaded Function Called when the form is open and loaded. x x x
onNextPage Function Called when the user navigates to the next page within the form. x x x
onPreviousPage Function Called when the user navigates to the previous page within the form. x x x
onCompletion Function Called when the user completes the form. x x x
onValidation Function Called when the form enters the validation state. x x x
onUserClosedForm Function Called when the user closes the form before it is completed. x x
custom Object Object containing custom user defined strings. Read more about text piping. x x x

Related Articles