DEV Community

Nazma Akter
Nazma Akter

Posted on

Installed, but nothing shows": building an install check for a third-party widget

#javascript #saas #webdev

Any product that ships a <script> tag for customers to paste into their site gets the same support ticket: "I installed it, but nothing shows." Most of the time the snippet is fine, and something else is in the way.

For VeloxonHub ProofLoom, our social proof widget, we built the setup flow so it ends when the widget is working, not when the code is copied. The 15-second reel shows the whole flow. Here's how it works.

Step 1: Prove you own the domain

A widget that shows "Liam from Austin just purchased…" on any domain that copies the snippet would be a problem, so notifications only run on verified domains. We offer two ways to verify, because different people control different things:

  • A DNS TXT record, for people who can reach their DNS. The setup screen explains that many providers (Cloudflare, GoDaddy, Namecheap…) add the root domain to the Name field automatically, so you only enter the subdomain part. This is the most common reason verification fails.
  • A verification file served at /.well-known/proofloom-verification.txt, for people who can upload files but can't change DNS.

Step 2: One script, with platform-specific steps

The snippet is the same everywhere:

<script async src="https://proofloom.veloxonhub.com/widget/v1/widget.js" data-site="site_…"></script>
Enter fullscreen mode Exit fullscreen mode

What changes from platform to platform is where to paste it, so the install panel asks "Where is your site built?" and shows the steps for WordPress, Shopify, Webflow, Wix, Squarespace, Next.js / React, Google Tag Manager or any site. Some no-code builders' code boxes don't accept <script> tags. For those, there's a plain JavaScript version that loads the same widget.

The script is async and never blocks rendering. If our servers are down, the customer's site works as usual. You lose the notifications, not the page.

Step 3: The install check

This is the part that cut down the support tickets. Test installation opens the customer's page from our server and runs a list of checks, each of which passes, fails, warns or is skipped:

  1. Domain verified. Is the host verified for this website?
  2. Snippet on the page. Can we open the page, and is the script tag there? If the page doesn't load, we show the actual error, such as a DNS lookup failure or a timeout, and point out that the page has to be public. Firewalls that block bots are a common cause.
  3. Site ID matches. Is it the snippet for this website, or one copied from another workspace or a staging site?
  4. Not blocked by Content Security Policy. A strict script-src or connect-src blocks the widget silently, with no visible error. We read the CSP header and tell the customer which directive needs our origin.

When we can't open the page, the later checks are marked "Checked once we can open your page" instead of failing. A failure would suggest that those checks found a problem.

The check also runs once on its own if a website has never seen the widget. "Installed, but zero visits" is the most confusing state, so we start explaining it before anyone asks.

Two smaller things that helped

  • Consent mode. Add data-consent="required" to the script tag, and the widget waits until your banner calls ProofLoom.consent(true).
  • A preview flag. Add ?proofloom_preview=1 to any page to see the widget with labelled sample data, without counting a visit. This lets customers check the design before they have any real activity.

Try it

14-day free trial, no card needed: https://proofloom.veloxonhub.com

If you've built an install flow for an embeddable widget, I'd like to hear which check caught the most problems for you.

Top comments (0)