Setting up a dev environment

Troubleshoot your embed before going live

It's worth noting that the Enterprise plan is the only one that allows access to multiple environments (staging, dev, etc.). If you are on the Free or Pro plans, this guide will still be helpful, but you will have to test with your Production environments. If you're interested in upgrading to Enterprise, chat us on Intercom!

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.

Whitelisting is required to prevent unknown domains from hosting your flow, with the added benefit that the parent page will have access to the user’s submission data.

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.

Trying to frame in an unlisted domain

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.

We suggest using nrgok because the basic service is free and is quick and easy to install, but feel free to use any proxy you're familiar with.

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.

Making a "dev" environment is optional. At your own discretion, you can opt for the staging environment instead. However, we suggest creating a third environment so that any developers have their own space and integration set to test with.

Add "dev" in the "Edits environment" menu

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

Setting up a webhook target for the dev environment

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

Select your dev environment and then ship that sucker

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:

The clientLabel and flowLabel props are also required, in any case

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

See our embed docs for more information about code requirements and syntax.

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.

Steps 2 and 3 in the ngrok install guide are sufficient to get the client installed.

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.

Whitelisting ngrok with the wildcard subdomain

Make sure to save after adding the domain!

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).

npm start to get the React project onto the localhost port 3000

You can close the window might be opened in your web browser.

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.

Open the ngrok.io Forwarding address in your browser

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”.

The "dev" environment flag

The forwarding address is publicly accessible on the internet, so anyone that has it will be able to test this flow. This will only stay active for as long as you have the ngrok service running in your terminal.

...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!