Setting up a dev environment

It's not uncommon to want to host your form on your own application, and using our web-embed capabilities will allow you to do this. But it's also important to have a safe environment to troubleshoot your embed page, or even experiment with different configurations without affecting the production flow.

Your first instinct (probably) is to set up a dev environment by serving up your embedding page on localhost and testing there, but there are two caveats with Formsort flows - any domain your flow is embedded into needs to be whitelisted in your studio, and localhost cannot be whitelisted.

If your embedding domain is not whitelisted in Formsort, the flow will not display on the page, and you’ll likely see a CSP: "frame-ancestor" error.

The process here is to use a proxy, like ngrok, which will make your localhost environment available on the internet by providing a forwarding address. This address can be whitelisted in Formsort.

This guide will show you how to get your dev environment set up and whitelist the required subdomain.

Getting Setup

What you’ll need:

• The correct roles and permissions for your Formsort studio account

  • Owner, Admin, and Engineer all have the requisite permissions

• A place to send test data

• The embed code for your flow

  • see our embed-docs for getting set up here

• If you're planning on using ngrok specifically, a free ngrok account

1. Create your environment

In order to receive test data at your integration targets, you’ll need to create integrations specific to the test environment.

• Create a “dev” environment in the Integrations menu of the flow you are going to be working in.

• Setup your integration target(s) in this new dev environment. Be sure to save your changes!

• Head into a variant you want to use and deploy it to your "dev" environment.

2. Configure your embed

Now, you’ll need to write the code instruction to load your flow into the new developer environment.

• Have the embed configuration pass in formsortEnv=dev as a query parameter.

The syntax for the query parameter here requires an array of string values. Below is the code for an example functional component in React:

This will allow the variant to load in the dev environment.

3. Install ngrok

If you don’t already have ngrok available, install it in the root project folder. You can see installation instructions on their official site.

4. Whitelist the embedding domain

Now we need to whitelist ngrok in your Formsort studio. Head to Setup -> Security in the left toolbar of your Studio view.

If you’re using the freemium version of ngrok, the easiest thing to do here would be to whitelist using a wildcard subdomain: *.ngrok.io. This is because ngrok will serve you a different subdomain every time you run the service.

If you already have a dedicated ngrok/proxy address, whitelist that instead.

5. Expose your project with ngrok

Once your project is ready to get online (any project dependencies have been configured and you are ready to test), serve it up on your local web service (localhost).

Now, in a separate terminal, have ngrok create a secure tunnel to make localhost accessible via the internet using the following command: ngrok http https://localhost:<your_port_here>. <your_port_here> is the port number your local web service is using.

Open the session in your browser using the forwarding address that is generated in the ngrok terminal.

Once you've navigated to the address in a browser, the tag at the top of the page should match the environment variable that you’ve passed in as the URL parameter in the embed code.

In our case here, it’s “dev”.

...And finally

That's it! Once you see the above page, your flow is live at the Forwarding address provided and you can start troubleshooting your page in your dev environment.

Happy coding!