Openstats - Full API Integration guide and Developer package

OpenStats Embed Widget — Integration Guide

> Add a live, interactive survey to any website in under 5 minutes.

Step 1 — Get Your Two Keys

You need two values from your OpenStats dashboard. Both come from the same page.

1. Log in at [openstats.live](https://openstats.live)

2. Go to your Dashboard and create a survey or pick one you want to embed

3. Click 🔌 API in the top of the survey card from the dashboard

4. Click Activate API (you only do this once)

5. Copy these two values:

You will paste these into whatever file you download in Step 2.

Step 2 — Download a Template

Go to [openstats.live/developer](https://openstats.live/developer) and pick a template that fits your website.

Click Download on the card you want. A single file downloads to your computer.

Step 3 — Open the File and Replace Two Values

Every downloaded file contains the same two placeholder values.

Open the file in any text editor (Notepad, VS Code, etc.) and replace:

YOUR_API_KEY_HERE → your real API key (starts with os_live_)

YOUR_SURVEY_ID_HERE → your real Survey ID

( Do not keep the double quote mark “api_key” before or after the keys )

That's it. Every file has comments inside that explain exactly where to paste them.

Step 4 — Add It to Your Website

HTML Website

Copy the `<div>` and `<script>` from the downloaded file into your page:

html

<!-- Put this where you want the survey to appear -->

<div id="openstats-survey"></div>

<!-- Put this just before </body>, AFTER the div above -->

<script

src="https://openstats.live/embed.js"

data-api-key="YOUR_API_KEY_HERE"

data-survey-id="YOUR_SURVEY_ID_HERE"

></script>

> ⚠️ The `<script>` must come after the `<div>`, otherwise the script loads

> before the container exists and the survey won't appear.

React / Next.js

1. Download the React Component template from [/developer](https://openstats.live/developer)

2. Save it as `src/components/OpenStatsSurvey.tsx` in your project

3. Create a `.env.local` file in your project root (same folder as `package.json`):

Add the following in the .env.local file ;

NEXT_PUBLIC_OS_API_KEY=os_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

NEXT_PUBLIC_OS_SURVEY_ID=your_survey_id_here

4. Use the component in any page:

```tsx

import OpenStatsSurvey from '@/components/OpenStatsSurvey';

export default function MyPage() {

return (

<OpenStatsSurvey

apiKey={process.env.NEXT_PUBLIC_OS_API_KEY!}

surveyId={process.env.NEXT_PUBLIC_OS_SURVEY_ID!}

/>

);

}

```

>In Next.js, env variables must start with `NEXT_PUBLIC_` to be available

in the browser. In Vite, use `VITE_` prefix and read with `import.meta.env.VITE_OS_API_KEY`.

WordPress

1. Download the WordPress Block template from [/developer](https://openstats.live/developer)

2. Replace the two placeholder values in the file

3. In WordPress editor → add a Custom HTML block

4. Paste the entire file content into the block

5. Click Publish or Update

Floating Popup Widget

1. Download the Floating Popup Widget template from [/developer](https://openstats.live/developer)

2. Replace the two placeholder values

3. Paste the code into your HTML page

The survey appears as a floating button in the corner of the page. Clicking it opens a popup panel with the survey inside.

Slide-in Banner

1. Download the Bottom Slide-in Banner template from [/developer]

( https://openstats.live/developer )

2. Replace the two placeholder values

3. Paste into your HTML page

A slim survey bar automatically slides up from the bottom of the screen after 3 seconds.

Show Survey on Button Click

1. Download the On-Demand Loader template from [/developer](https://openstats.live/developer)

2. Replace the two placeholder values

3. Use it like this:

```html

<button id="open-survey-btn">Take our survey</button>

<div id="openstats-survey"></div>

<script src="openstats-loader.js"></script>

<script>

document.getElementById('open-survey-btn').addEventListener('click', function () {

loadOpenStatsSurvey('YOUR_API_KEY_HERE', 'YOUR_SURVEY_ID_HERE');

});

</script>

```

Step 5 — Allow Your Domain (Security)

This stops other websites from using your API key.

1. Go to Dashboard → 🔌 API

2. Find Allowed Domains

3. Add your website domain — just the hostname, no `https://` and no paths:

> Subdomains like `www.mysite.com` and `mysite.com` are treated separately —

> add each one you need. For local testing, add `localhost`.

🔐 Is the API Key Safe to Put in HTML?

Yes. The embed API key is intentionally designed to be public. It can only do one thing: submit survey responses to your specific survey. It cannot read your data, access your account, or do anything else.

This is the same model used by Google Analytics, Stripe.js, and similar embed tools.

Controlling the Size

The widget is 560px wide by default. Wrap it in a container to control layout:

```html

<!-- Centered -->

<div style="max-width: 560px; margin: 2rem auto;">

<div id="openstats-survey"></div>

</div>

<!-- Full width -->

<div style="width: 100%;">

<div id="openstats-survey"></div>

</div>

```

❓ Troubleshooting

| Problem | What to check |

| Survey doesn't appear | Is `<div id="openstats-survey">` in your HTML before the `<script>` tag? |

| "Survey not found" | Copy your Survey ID again from Dashboard → 🔌 API |

| "API key invalid" | Copy your API key again — it must start with `os_live_` . Keep the single quote and remove the double quote |

| "Domain not allowed" | Add your domain in Dashboard → 🔌 API → Allowed Domains |

| Doesn't work on localhost | Add `localhost` to your Allowed Domains list |

| 403 error in browser console | Your API key or survey may be suspended — check Dashboard → 🔌 API |

| CORS error in browser console | Your domain is not in Allowed Domains, or the format is wrong (remove `https://`) |

Pricing

| Free quota | 50 submissions shared across all your surveys — no time limit |

| After free quota | $0.02 per submission |

| Minimum top-up | $20 (1,000 submissions) |

| Credits | Never expire |

Top up from Dashboard → 🔌 API → Top Up Credits.

Privacy

The embed widget collects only the answers users give to your survey questions, plus a session ID to prevent duplicate submissions. It does not set tracking cookies or collect personally identifiable information unless your own questions ask for it.

See [openstats.live/data-usage](https://openstats.live/data-usage) for full details.