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: TRUE (pass false to keep it open)	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
onComplete	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