LogoLogo
Back to studio
  • Formsort documentation
  • โฉQuickstart
    • ๐ŸŸขGet started with Formsort
    • ๐ŸŽCore concepts
    • โ„น๏ธQuestion and content reference
    • ๐Ÿ“•Key terms
    • ๐Ÿž๏ธCreate your first flow
    • ๐Ÿ“–Add content and collect answers
      • ๐ŸคณCapture demographic data
      • โ„น๏ธAdd informational content
      • ๐Ÿ” Review your variable schema
    • ๐ŸŽจCreate a theme
      • Set brand guidelines
    • ๐ŸคนPersonalize your flow
      • ๐ŸŒŸTemplate your variables
      • ๐Ÿง Add conditional logic
      • ๐Ÿ’ซUsing conditional logic with Calculated and API variables
      • ๐Ÿ”šEnd the flow
    • ๐Ÿ”€Set up integrations
    • ๐Ÿš€Go live
      • Auditing your flow for content, functionality, and design
    • ๐Ÿ’ผCommon use cases
      • ๐Ÿ’”Disqualify responders
      • ๐Ÿ—“๏ธAdd a scheduling option
      • ๐Ÿ“„Allow responders to read and accept your company policies
  • ๐Ÿ—๏ธBuilding flows
    • Flows and variants
      • Flow starts
    • Adding content
      • Groups
      • Steps
        • Settings
        • Logic
        • Style
      • Questions
        • General Settings
        • Style
        • Address
        • Comparison
        • Confirmation
        • Date
        • Date & Time
        • Email address
        • File upload
        • Grid choice
        • Iframe
        • Image upload
        • Number
        • Payment
        • Phone number
        • Postal code
        • Question group
        • Region
        • Select
          • Providing choices via API or calculation
        • Signature
        • SSN
        • Text questions
        • Yes/No
      • Content
        • General Settings
        • Statement
        • Image
        • Video
        • Next button
        • Divider
        • Map
      • Endings
      • Using markdown
      • Using variable templating
        • Template formatting functions
      • Copy-pasting form content
      • Content library
    • Conditions and logic
      • Logical operator reference
      • Advanced logic
    • Variables (answers)
      • Variables from questions
      • Externally provided variables
      • Calculated variables
      • API lookups
      • System Library variables
      • Orphaned variables
    • Schemas
      • JSON Schemas
      • Validating flow schemas
    • Redirects
    • Styling and themes
      • CSS Reference
      • Overriding theme styling
      • Custom CSS overrides
      • Content area
      • Animations and transitions
      • Form Layout
      • Typography
        • Adobe Fonts
        • Hosting custom fonts
      • Color variables
      • Dimension variables
      • Question containers
      • Assets
      • Form Buttons
        • Select buttons
      • Inputs and dropdowns
      • Checkmarks
      • Tables
      • Sliders
      • Divider lines
      • Progress bar
      • Comparison cards
    • Variant settings
      • Form behavior for returning responders
      • Group ranking API
    • Publishing and versions
      • Preview window
      • Deploying
      • History
  • ๐Ÿ’พHandling data
    • Philosophy and data retention policy
    • Viewing form answers
    • Responder UUIDs
    • Environments
      • Loading different environments
    • Passing data in
      • URL parameters
      • POST body
      • Embed query parameters
    • Custom validators
    • Form answers and events
      • Analytics events
      • Signed requests
      • Event payload shape
      • Submission frequencies
      • Runtime error reporting
      • Admin API
      • Flow content data format
    • Integration reference
      • Amplitude
        • Amplitude cross domain tracking
      • BigQuery
      • FullStory
      • Google Analytics
        • Updating from Universal Analytics to GA4
      • Google Cloud Storage
      • Google Sheets
      • Google Tag Manager (GTM)
        • JavaScript triggered by flow events
      • Hubspot
      • Jornaya
      • Optimizely
      • PostgreSQL
      • Redshift
      • Rudderstack
      • S3
      • Salesforce
      • Segment
        • Segment Setup
        • Segment cross domain tracking
      • Stripe
      • TrustedForm
      • Webhooks
        • Zapier
  • ๐Ÿ“บGoing live
    • Custom domains
    • Built-in analytics
    • Embedding
      • Web-Embed API
        • React-embed
      • Adding authentication
      • Embedding forms in iOS and Android
      • Setting up a dev environment
    • Split testing
    • Preflight checklist
  • ๐ŸขTeams
    • Accounts
      • Roles and permissions
    • Events subscriptions
    • Workspace domain detection
Powered by GitBook
On this page
  • Getting Setup
  • 1. Create your environment
  • 2. Configure your embed
  • 3. Install ngrok
  • 4. Whitelist the embedding domain
  • 5. Expose your project with ngrok
  • ...And finally

Was this helpful?

  1. Going live
  2. Embedding

Setting up a dev environment

Troubleshoot your embed before going live

PreviousEmbedding forms in iOS and AndroidNextSplit testing

Last updated 10 months ago

Was this helpful?

It's worth noting that the 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 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 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.

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:

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

  • A place to send test data

  • The embed code for your flow

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.

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

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

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.

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

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

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โ€.

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!

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

The correct for your Formsort studio account

see our for getting set up here

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

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

See our for more information about code requirements and syntax.

If you donโ€™t already have ngrok available, install it in the root project folder. You can see installation instructions .

Now, in a separate terminal, have ngrok create a secure tunnel to make 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.

๐Ÿ“บ
ngrok
localhost
roles and permissions
embed-docs
ngrok account
deploy
embed docs
on their official site
localhost
Enterprise
web-embed
whitelisted
Trying to frame in an unlisted domain
Add "dev" in the "Edits environment" menu
Setting up a webhook target for the dev environment
Select your dev environment and then ship that sucker
The clientLabel and flowLabel props are also required, in any case
Whitelisting ngrok with the wildcard subdomain
npm start to get the React project onto the localhost port 3000
Open the ngrok.io Forwarding address in your browser
The "dev" environment flag