Installation | Rooster Docs

1. Add Your Website

Open Websites, click Add website, and enter the same domain where the scripts will run.

Use:

example.com
app.example.com
localhost:5173

Do not use:

https://example.com
rooster.host
api.rooster.host
rooster.ink

Rooster creates a default form group automatically. Expand the website row after saving to copy scripts, create more form groups, and check installation status.

2. Install Analytics

Install the analytics script in your site layout, app shell, tag manager, or shared template.

<script src="https://api.rooster.host/analytics/YOUR_PUBLIC_KEY.js" defer></script>

The analytics script:

Records page visits and visitor context.
Enforces page-level bot protection.
Can show the CAPTCHA or block overlay.
Does not read, serialize, submit, or store form field values.
Is safe to install globally in an app layout, root template, tag manager, or shared header.

3. Install Form Collection

Install the form collector script on pages where Rooster should collect existing forms. Form collection can also report form-page activity so the dashboard knows the collector is installed.

<script src="https://rooster.ink/embed/YOUR_PUBLIC_KEY.js" data-rooster-form="default" defer></script>
<form>
  ...
</form>

The form collector script:

Collects form submissions.
Reports form-page activity for analytics and collection health.
Handles form-level bot protection before submissions are accepted.
Can map a form to a non-default form group with data-rooster-form.
Should usually be installed only on pages where forms should be collected.

Do not install the form script globally unless you mean to

Adding the form script in layout.tsx, a root app file, or a global template can collect form data from every route in your app. Use Form settings on the Websites page to allow or ignore specific routes when a global install is intentional.

Replace YOUR_PUBLIC_KEY with the key shown in Rooster. The exact domains may differ if your workspace shows different install instructions.

Form Groups

Every website starts with the default form group. You can create up to three form groups per website so different forms do not get mixed together.

Use form groups when:

The homepage newsletter form should be separate from the contact form.
A sales form should route to a sales group.
A support form should route to a support group.

To create a group:

Open Websites.
Expand the website row.
Click Add new form in the form groups section.
Enter the form group name and key.
Copy the script for that form group.
Add the same data-rooster-form key to the target form.

<script src="https://rooster.ink/embed/YOUR_PUBLIC_KEY.js" data-rooster-form="sales" defer></script>
 
<form data-rooster-form="sales">
  <input name="work_email" type="email" required />
  <button type="submit">Request demo</button>
</form>

If the script has data-rooster-form="sales" but the form is missing data-rooster-form="sales", the script will ignore that form. The script key and form key must match for specific group collection.

Collect every form

Remove data-rooster-form from the script only when the script should scan every form on that page. In that mode, each form can still choose a group with data-rooster-form, or fall back to default.

Form Route Controls

Open Websites, use the website action menu, and choose Form settings to control where form submissions can be saved.

Allowed form routes:

If empty, form submissions are allowed by default.
If configured, only those routes and child paths can save submissions.
Example: /contact allows /contact and /contact/team.

Ignored form routes:

Always block form submission storage for those routes and child paths.
Ignored routes override allowed routes.
Use this for routes such as /login, /signup, /admin, and /billing.

When a route is blocked, Rooster accepts the collector request without saving a submission. Existing form-script analytics metadata can still be recorded through the form detection flow.

Website Status

The website row status shows whether Rooster has verified the scripts on the expected website URL.

PendingThe website was added, but Rooster has not seen a valid analytics page view or collector detect event yet.Visit the installed page after publishing and refresh the dashboard.

ActiveRooster has seen a valid script event from the website URL.Run a test form submission if this website should collect forms.

InvalidThe script is being called from a different origin than the website URL saved in Rooster, or no active form group can be matched.Edit the website URL or move the script to the matching domain.

DisconnectedA previously active form page no longer appears reachable during status checks.Open the last form page, confirm it is public, then submit a test form.

Form Group Status

The form group status shows whether that group has been detected or used.

PendingThe form group exists, but the collector has not detected or submitted this group yet.Open the page with the matching script and form key.

ActiveThe collector detected the form group or saved a submission for it.Keep the script on the page where the form lives.

InvalidThe collector request came from a domain that does not match the website URL, or the mapping could not be resolved.Confirm the website URL and the `data-rooster-form` key.

DisconnectedThe last known page for this form group is no longer reachable.Restore the page or move the script to a valid page.

Submission Health

The expanded website row also shows submission health for collection.

Not activeNo embed activity has been confirmed yet.Publish the collector script and open the public page.

Not confirmedThe collector script has been seen, but no form submission has been received yet.Submit a test form from the public page.

ReceivingRooster has received form submissions for this website.Review submissions and analytics.

FailingThe collector is failing, usually because the origin does not match the website URL or a form mapping is missing.Fix the website URL, form group key, or page placement.

4. Verify

Open your website in a browser.
Visit a few pages to trigger analytics.
Submit a test form to trigger collection.
Open Rooster.
Confirm page views appear in analytics.
Confirm the test submission appears in submissions.

Placement

Use this placement for most apps:

Put the analytics script in the global layout.
Put the form collector script on pages with forms, or in the global layout only when every public form should be collected.
Avoid putting the form collector on login, signup, payment, or admin pages unless those forms should be collected.

For single-page apps, the analytics script tracks first load and client-side route changes.