Quickstart

Code Sandboxes

The fastest way to build a Setster Studio embed is to use one of our code sandboxes or demos. Here, you'll find all the necessary components to building, customizing, and embedding a Setster Studio embed. We've made it as simple as possible to start with just two files you'll be working with: the index.html file and the setttings.json file. First, we'll discuss the HTML file and then the JSON settings file.

Try the Starter Demo to explore the settings.json configuration file for all available step types.

Create Account

If you haven't already you'll need to create a Setster account and collect a few required details. See Create Account Guide.

Embed HTML

The SetsterStudio.init() function accepts three arguments: embed_id, settings_json, and custom_field_defaults.

tip

Details on setting the third argument, custom_field_defaults for prefilling data are documented in the Custom Data section of these docs.

The entire embed and initialization script looks something like this. In the next section, we'll walk through all the different parts of embed script.

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=480" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Setster app</title>
  </head>
  <body>
    <!-- Here we'll create a <div> element with the id that we'd like to embed to app on to.-->
    <div id="embed-1"></div>

    <!-- Here we add the scripts to run app by fetching the settings JSON file to pass along with the embed id to SetsterStudio.init() function. After intialized, we load the app bundle from the JSDelivr CDN -->
    <script>
      window.onload = (event) => {
        fetch("./settings.json")
          .then((response) => response.json())
          .then((settings) => {
            window.embedSettings = settings;
            var script = document.createElement("script");
            script.onload = function () {
              if (window.SetsterStudio) {
                SetsterStudio.init("embed-1", settings);
              }
            };
            // Load the app bundle from JSDelivr
            script.src =
              "https://cdn.jsdelivr.net/npm/@setster/setster-studio-core@1.1.0-alpha/build/app.bundle.js";
            document.head.appendChild(script);
          })
          .catch((err) => {
            console.log(err);
          });
      };
    </script>
  </body>
</html>

Installation

To create a Studio embed, simply add the embed scripts to your existing project:

Create a new <div> somewhere on your website to house your embed and add an identifying ID:

<div id="embed-id"></div>

Create a new .json file to hold all your embed settings and configurations.
Copy the starter settings file contents into your newly created settings.json file.
Create a promise to fetch your settings file from wherever you've placed it on your server's file system for the initialization script and set window.embedSettings. Be sure to replace the "./settings.json" in the promise below with the location that you've saved your settings.json file to.

fetch("./settings.json")
  .then((response) => response.json())
  .then((settings) => {
    window.embedSettings = settings;
  })
  .catch((err) => {
    console.log(err);
  });

Dynamically create a new <script> to append to the DOM with an onload() listener.

fetch("./settings.json")
  .then((response) => response.json())
  .then((settings) => {
    window.embedSettings = settings;
    var script = document.createElement("script");
    script.onload = function () {
      // Do something
    };
    document.head.appendChild(script);
  })
  .catch((err) => {
    console.log(err);
  });

Initialize the Studio embed when the script loads.

Pass the settings to the SetsterStudio.init() function, ensuring to pass the same "embed-id" you previously added to the DOM as the first argument
Pass the fetched settings object as the second argument

info

Your initialization script should look like this as shown below: SetsterStudio.init('embed-1', settings)

fetch("./settings.json")
  .then((response) => response.json())
  .then((settings) => {
    window.embedSettings = settings;
    var script = document.createElement("script");
    script.onload = function () {
      if (window.SetsterStudio) {
        SetsterStudio.init("embed-1", settings);
      }
    };
    document.head.appendChild(script);
  })
  .catch((err) => {
    console.log(err);
  });

Load Setster Studio from JSDelivr like: https://cdn.jsdelivr.net/npm/@setster/setster-studio-core@1.1.0-alpha/build/app.bundle.js.

info

You can use different versions, but it's best to pick one and stick to it for major versions. See All Versions

fetch("./settings.json")
  .then((response) => response.json())
  .then((settings) => {
    window.embedSettings = settings;
    var script = document.createElement("script");
    script.onload = function () {
      if (window.SetsterStudio) {
        SetsterStudio.init("embed-1", settings);
      }
    };
    script.src =
      "https://cdn.jsdelivr.net/npm/@setster/setster-studio-core@1.1.0-alpha/build/app.bundle.js";
    document.head.appendChild(script);
  })
  .catch((err) => {
    console.log(err);
  });

Add the loading script to your HTML document in the <body> tag.

<html lang="en">
  <head>
    ...
  </head>
  <body>
    <div id="embed-1"></div>
    <script>
      window.onload = (event) => {
        fetch("./settings.json")
          .then((response) => response.json())
          .then((settings) => {
            window.embedSettings = settings;
            var script = document.createElement("script");
            script.onload = function () {
              if (window.SetsterStudio) {
                SetsterStudio.init("embed-1", settings);
              }
            };
            script.src =
              "https://cdn.jsdelivr.net/npm/@setster/setster-studio-core@1.1.0-alpha/build/app.bundle.js";
            document.head.appendChild(script);
          })
          .catch((err) => {
            console.log(err);
          });
      };
    </script>
  </body>
</html>

App Versions

Alpha During the alpha release phase of Setster Studio, we recommend using the alpha tagged version of the app served from JSDelivr.

https://cdn.jsdelivr.net/npm/@setster/setster-studio-core@1.1.0-alpha/build/app.bundle.js

Latest

To use the latest version of the app, use the latest tagged version of the app.

caution

Using the latest version of the app bundle could cause breaking changes to your configurations as updates are made to the library.

Versioning Add the desired version to the JSDelivr script to use a specific version number.

https://cdn.jsdelivr.net/npm/@setster/setster-studio-core@1.0.17/build/app.bundle.js where the version equals setster-studio-core@1.0.17. However, with caution, you can also set this to use the latest version by specifying it with the setster-studio-core@latest

JSON Settings

All the content for your app embed is configured in the settings file.

account_id: Enter your Setster account's ID. See Find Account ID
embed_id: This id should match up the element id in your HTML content that you'd like for your Setster Studio embed to appear in. In our example HTML above, we've decided to give it the id of embed-1.
Set developer_mode to true for development purposes
Set the base_url to the url location that Studio embed is embedded on being sure to include a trailing slash. This will enable your embed to access the your image assets.
Use the settings_version property to force the app to update your embeds when you make updates to your settings.json file after you've launched your embed on a live site and no longer are using the developer_mode flag.

{
  "embed_id": "embed-1",
  "developer_mode": true,
  "account_id": 19198,
  "settings_version": "0.0.1",
  "base_url": "https://www.setster.com/sales-appointment/",
  "steps": {}
}

developer_mode

Typically, the app persists user selections between sessions on the same device. This means that users won't have to restart the form flow from the beginning if they drop off and revisit it later. While this is a fantastic user experience, it doesn't make for a great developer experience since changes to the content wouldn't be immediately reflected as the previous configurations were being persisted. To ensure the preview of your changes is readily available upon saving your settings file and refreshing the page, we've added the developer_mode property, which will reset the persisted settings when the page is refreshed so that you can see your changes immediately.

When working on building your Setster Studio, embed set developer_mode to true. Then, when you're ready to go live with your embed, change this property to false.

Quickstart

Code Sandboxes​

Create Account​

Embed HTML​

Installation​

App Versions​

JSON Settings​

developer_mode​