Embedding

Embedding Voiceform into Your App

Integrating Voiceform into your app is straightforward. Follow these steps:

1. Navigate to the Share tab of your survey.
2. Locate the section labeled "Embed in a web page."
3. You will find six embedding options available: Standard, Single Question, Full-Page, Popup, Slider, Popover, and Side Tab.
4. Select one of the options and configure it using the available settings under Embed Settings.
5. Click the "Get code" button, then copy the generated code.
6. Paste the code into your webpage.

For detailed information on each embedding type, please continue reading the document.

Embedding Types

Standard Type

The Standard widget (data-mode="standard") displays the survey as part of you website content. Useful if you want to make a survey as one of the section on ypur website. In case if for some reason your web page does not allow passing a

Widget Properties

Single Question Type

The Single Question widget (data-mode="single-question") is similar to the Standard widget type, but it allows you to embed only one question at a time. This option is commonly used when you want to integrate Voiceform into another survey or form experience. The widget automatically adjusts its height based on its content. If you cannot use a

Widget Properties

Full-Page Type

The Full-Page widget (data-mode="popup") is used when you want the survey to occupy the entire web page. This option is commonly used when you want to host the survey on your own domain and serve it directly from there.

Popup Type

The Popup widget (data-mode="popup") is designed to overlay the page and appear as a dialog module. This widget also includes a customizable triggering button, which can be placed within any content on your page.

Widget Properties

Slider Type

The Slider widget (data-mode="slider") is similar to the Popup widget, but instead of overlaying the entire page, the form slides in from the right side of the screen. It also includes a customizable triggering button that can be placed anywhere within your webpage content.

Widget Properties

Popover Type

The Popover widget (data-mode="popover") adds a floating button to the bottom right corner of the screen. When toggled, the survey will pop up in a manner similar to a customer support chat button. This widget is commonly used for customer support or for collecting feedback.

Widget Properties

Side Tab Type

The Side Tab widget (data-mode="side-tab") is similar to the Slider widget but features a fixed-position toggle button on the right side of the screen.

Widget Properties

Passing Custom Attributes

Sometimes, you might need to pass custom attributes into a survey, such as metadata or the value of a dynamic variable. There are two ways to pass this data:

Option 1: Passing Metadata through Custom Attributes

You can pass metadata by adding a custom attribute to the <vf-widget /> element. For example, if you want to pass a respondent's email into the survey metadata, you would include a custom attribute with the data- prefix, like data-email="". The email attribute will then be passed as a query parameter to the survey link.

Example:

<vf-widget
      data-vf-height="600px"
      data-vf-width="100%"
      data-mode="standard"
      data-hash="9V7GKLwJs2jkBbMt"
      data-email="[email protected]" <!-- passing custom attribute -->
/>

Option 2: Passing Multiple Data Items Using data-metadata

When you need to pass multiple data items, you can use the data-metadata attribute. This attribute accepts a JSON string, where each key-value pair will be converted into query parameters for the survey link.

Example:

<vf-widget
      data-vf-height="600px"
      data-vf-width="100%"
      data-mode="standard"
      data-hash="9V7GKLwJs2jkBbMt"
      data-metadata='{"email":"[email protected]", "userId":"12345", "source":"newsletter"}' 
/>

In this example, the email, userId, and source keys will be passed as query parameters, allowing you to dynamically include various pieces of metadata in your survey.

Manually Triggering Next

Sometimes you may want to trigger the next or finish button outside of the survey. For example, if you're using the Single Question widget, you can hide the default next button and use your own custom button. To achieve this, you'll need to use the VoiceformJS SDK, which is automatically included on the web page when the widget script is added to the header:

<script src="https://cdn.voiceform.com/widgets/next/widgets.umd.js"></script>

To confirm that the SDK is available, you can open Chrome DevTools and type voiceform in the console. You should see the VoiceformJS class as a return value.

The VoiceformJS class has a next method, which requires an HTMLElement as a parameter. In our case, we need to pass the <vf-widget /> element as the parameter. To simplify this, we can assign an id to the widget, like so: <vf-widget id="my-widget" />. Then, we can use document.getElementById to get the HTML element and pass it to the voiceform.next() function.

Please see the example below:

Listening to Survey Events

Voiceform widgets contain an iframe that posts messages to the parent window. You can listen to these message events to implement custom logic based on the survey's state.

Supported Events

The following events are currently supported:

Example: Handling Survey Events

The following example demonstrates how to handle survey events. In this scenario, the survey widget is hidden upon successful submission, and a record of the submission is stored in local storage:

window.addEventListener("message", function(event) {
  // Validate the origin of the message (optional)
  if (event.origin !== "https://app.voiceform.com") {
    return;
  }

  // Process the message based on its type
  switch(event.data.type) {
    case "voiceform.form-submitted":
      // Hide the survey widget upon successful submission
      const surveyWidget = document.querySelector("vf-widget");
      if (surveyWidget) {
        surveyWidget.style.display = "none";
      }

      // Store submission status in local storage
      localStorage.setItem("surveySubmitted", "true");
      console.log("Survey submitted successfully, and status stored in local storage.");
      break;

    case "voiceform.form-submission-error":
      console.error("Survey submission failed with error:", event.data.errorMessage);
      break;

    // Additional cases can be added here as needed
  }
});