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
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.
- Owner, Admin, and Engineer all have the requisite permissions
- A place to send test data
- The embed code for your flow
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
Select your dev environment and then ship that sucker
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=devas 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.
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.
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!
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.
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!
Last modified 6mo ago