Documentation

Complete guide to using ScriptVitals for 3rd-party script performance monitoring

Quick Start

Create an Account

Add Your Website

After logging in, navigate to Sites and click "Add Site". Enter your website's primary domain.

Required: Primary domain (e.g., example.com)
Optional: Site name, environment (production/staging)

Install the SDK

Add this snippet to your HTML, right before the closing </head> tag:

HTML

<script src="https://cdn.scriptvitals.com/sdk/latest/scriptvitals.min.js"
        data-site-key="YOUR_SITE_KEY"></script>

Verify Installation

Visit your website and open browser DevTools. In the Console, you should see:

Console

✓ ScriptVitals SDK loaded
✓ Site key verified
✓ Monitoring started

Return to your dashboard - data will appear within 2-5 minutes.

SDK Installation

CDN Installation (Recommended)

The fastest way to get started. Add this snippet to your HTML:

HTML

<script src="https://cdn.scriptvitals.com/sdk/latest/scriptvitals.min.js"
        data-site-key="YOUR_SITE_KEY"></script>

NPM Installation

For modern build tools and frameworks:

BASH

npm install @scriptvitals/sdk

JavaScript

import { init } from '@scriptvitals/sdk';

init({
  siteKey: 'YOUR_SITE_KEY',
  sampleRate: 1.0,
  reportAllChanges: true
});

Configuration Options

Option	Type	Default	Description
siteKey	string	required	Your site's unique key
sampleRate	number	1.0	Percentage of sessions to track (0-1)
reportAllChanges	boolean	false	Report all metric changes or final only
debug	boolean	false	Enable console logging

3rd-Party Script Attribution

The Core Differentiator

ScriptVitals is the only platform that automatically identifies and measures which 3rd-party scripts are slowing down your website. No manual configuration, no guessing.

How Script Detection Works

ScriptVitals uses the browser's PerformanceObserver API to automatically detect and track all 3rd-party scripts loaded on your pages. Scripts are identified by their origin domain and categorized automatically.

Automatic Detection

Common scripts like Google Analytics, Facebook Pixel, chat widgets, and tag managers are automatically recognized and attributed. No manual configuration required.

How It Works

Automatic Detection

SDK monitors all script requests using PerformanceObserver API

Pattern Matching

Identifies scripts by domain (google-analytics.com, facebook.net, etc.)

Impact Calculation

Measures blocking time, load duration, and impact on Core Web Vitals

Attribution Report

View script-by-script breakdown in dashboard with optimization recommendations

Core Web Vitals

LCP Largest Contentful Paint

Measures loading performance. Marks the time when the largest content element becomes visible.

Good: < 2.5sNeeds Work: 2.5-4sPoor: > 4s

FCP First Contentful Paint

Measures when the first content element appears on screen.

Good: < 1.8sNeeds Work: 1.8-3sPoor: > 3s

CLS Cumulative Layout Shift

Measures visual stability. Quantifies unexpected layout shifts during page load.

Good: < 0.1Needs Work: 0.1-0.25Poor: > 0.25

INP Interaction to Next Paint

Measures responsiveness. Time from user interaction to visual response.

Good: < 200msNeeds Work: 200-500msPoor: > 500ms

TTFB Time to First Byte

Measures server response time. Time from navigation to receiving first byte.

Good: < 800msNeeds Work: 800-1800msPoor: > 1800ms

Configuration

Configure sampling rate and reporting behavior through the dashboard under Site Settings.

Sample Rate

Control what percentage of traffic to monitor (0% to 100%). Useful for high-traffic sites to manage data volume and costs.

100%

Track all sessions
(Default)

10%

High-traffic sites
(>1M views/month)

Very high traffic
(>10M views/month)

Allowed Origins

Configure which domains can send data to prevent unauthorized usage. Set in dashboard under Site Settings → Security.

Example:
• https://example.com
• https://www.example.com
• https://staging.example.com

Dashboard Guide

Sites Overview

The main dashboard shows all your monitored websites with:

Overall performance score (0-100)
Core Web Vitals at a glance (LCP, FCP, CLS, INP, TTFB)
Daily event count
Site status and environment

Site Detail Tabs

Overview

Performance summary, trends, and Core Web Vitals charts

Domains

Add and verify domain ownership using DNS or HTML verification

Alerts

Configure performance threshold alerts with email, Slack, or webhook notifications

Webhooks

Set up webhook endpoints for real-time performance event notifications

Experiments

Create A/B tests to measure performance impact of changes

Usage

View daily event volume and billing information

Alerts & Notifications

Get instant notifications when your website's performance degrades or when specific 3rd-party scripts cause issues.

Setting Up Alerts

1. Navigate to Site → Alerts tab
2. Click "Create Alert"
3. Configure metric, threshold, and channel

Alert Channels

Email

Send alerts to specified email addresses

Slack

Post notifications to Slack channels

Webhook

Send to custom webhook endpoints

Example Alert Configuration

JSON

{
  "name": "LCP Threshold Alert",
  "metric": "lcp",
  "condition": "above",
  "threshold": 2500,
  "percentile": 75,
  "window": 60,
  "channel": "slack",
  "target": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
}

A/B Testing & Experiments

Test the performance impact of code changes, script additions, or optimizations before rolling out to all users.

Creating an Experiment

Define Variants

Control (current) vs Treatment (new change)

Set Traffic Split

50/50, 90/10, or custom ratio

Run & Analyze

View comparative performance metrics

Use Case Example: Test if removing Facebook Pixel improves LCP. Control group loads all scripts, treatment group removes FB Pixel. Compare LCP between groups.

Webhook Integrations

Connect ScriptVitals to your existing tools and workflows using webhooks.

Supported Events

performance.degradation

Triggered when metrics exceed thresholds

script.detected

New 3rd-party script detected

experiment.completed

A/B test reaches statistical significance

alert.triggered

Performance alert fired

Webhook Payload Example

JSON

{
  "event": "performance.degradation",
  "site": {
    "id": "site_abc123",
    "name": "example.com",
    "domain": "example.com"
  },
  "metric": "lcp",
  "current_value": 3200,
  "threshold": 2500,
  "severity": "high",
  "timestamp": "2025-10-20T14:30:00Z"
}

Team Management

Collaborate with your team and control access to specific sites.

User Roles

Role	Permissions
Owner	Full access - manage billing, delete account, invite/remove users
Admin	Manage sites, alerts, experiments, invite members
Member	View assigned sites, cannot modify settings

Inviting Team Members

1. Go to Account Settings → Team tab
2. Click "Invite User"
3. Enter email and select sites they can access
4. User receives invitation email

Domain Verification

Verify domain ownership to prevent unauthorized monitoring and ensure data accuracy.

Verification Methods

DNS Verification (Recommended)

Add a TXT record to your DNS configuration:

DNS

Type: TXT
Name: @
Value: scriptvitals-verify=YOUR_VERIFICATION_TOKEN

HTML File Upload

Upload a verification file to your website root:

FILE

https://example.com/scriptvitals-verification.html

Meta Tag

Add a meta tag to your homepage:

HTML

<meta name="scriptvitals-verify" content="YOUR_TOKEN">

Troubleshooting

No Data Appearing in Dashboard

Common Causes:

SDK script tag not properly installed
Incorrect site key
JavaScript errors blocking SDK initialization
Ad blocker interfering with beacon requests
Sample rate set to 0%

Solution:

Open browser DevTools → Console tab
Look for "ScriptVitals SDK loaded" message
Check Network tab for requests to scriptvitals.com
Verify site key matches dashboard

Domain Verification Failing

Common Causes:

DNS changes not yet propagated (can take up to 48 hours)
Incorrect TXT record format
Verification file not accessible

Solution:

Use DNS lookup tools to verify TXT record
Ensure verification file returns 200 status code
Try alternative verification method

Performance Scores Seem Wrong

ScriptVitals shows Real User Monitoring (RUM) data, which reflects actual user experiences. This can differ from lab testing (Lighthouse, GTmetrix) because:

RUM includes real network conditions and device variety
Lab tests use simulated conditions and don't load 3rd-party scripts
Different metrics tracked (P75 vs median)

Support

Need help? We're here to assist you with setup, troubleshooting, and optimization.

Email Support

Get help from our support team:

support@scriptvitals.com

Support Tickets

Create a support ticket from your dashboard (Account → Support tab)

Contact Form

For general inquiries and sales:

scriptvitals.com/contact

Enterprise Support

Dedicated support with SLA for Enterprise customers