Documentation | SocialProof

Quick Start

Get up and running in under 2 minutes.

1. Create a widget

2. Add the script tag

Paste this into your website's <head> or before </body>:

<script src="https://socialproof.tech/widget.js"
  data-widget-id="YOUR_WIDGET_ID"></script>

The script is 2.9 KB gzipped, loads asynchronously, and never blocks your page.

3. Send your first event

Once the script loads, call the SDK from your frontend JavaScript:

SocialProof.track('signup', {
  name: 'Sarah',
  location: 'Denver, CO'
});

A notification will appear on your website within seconds.

Client-Side SDK

The widget script exposes a global window.SocialProof object. No imports or build tools needed — it's available as soon as the script loads.

SocialProof.track(type, data?)

Send an event that triggers a notification on your website.

Parameters

Param	Type	Required	Description
`type`	string	Yes	Event type. See Event Types.
`data.name`	string	No	Person's name (max 100 chars)
`data.location`	string	No	Location text, e.g. "Denver, CO" (max 100 chars)
`data.message`	string	No	Custom message (max 200 chars)
`data.url`	string	No	URL to link the notification to

Returns

A Promise<{ id: string }> that resolves with the created event ID.

Examples

// Track a signup
SocialProof.track('signup', {
  name: 'Sarah',
  location: 'Denver, CO'
});

// Track a purchase on button click
document.getElementById('buy-btn').addEventListener('click', () => {
  SocialProof.track('purchase', {
    name: 'Alex',
    message: 'Pro Plan'
  });
});

// Track a review
SocialProof.track('review', {
  name: 'Maria',
  message: '5 stars'
});

// Low stock alert (Pro only)
SocialProof.track('low_stock', {
  message: 'Only 3 left in stock!'
});

// Handle errors
SocialProof.track('signup', { name: 'Test' })
  .then(res => console.log('Event ID:', res.id))
  .catch(err => console.error('Failed:', err.message));

Properties

Property	Type	Description
`SocialProof.widgetId`	string	The widget ID from the script tag
`SocialProof.apiBase`	string	The API base URL

REST API

Send events from your backend when you need server-side control. No authentication required — events are scoped to your widget ID.

POST /api/events

Create a new event that triggers a notification.

Request

curl -X POST https://socialproof.tech/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "YOUR_WIDGET_ID",
    "type": "signup",
    "name": "Sarah",
    "location": "Denver, CO"
  }'

Request Body

Field	Type	Required	Description
`widgetId`	string (UUID)	Yes	Your widget ID from the dashboard
`type`	string	Yes	Event type. See Event Types.
`name`	string	No	Person's name (max 100 chars)
`location`	string	No	Location text (max 100 chars)
`message`	string	No	Custom message (max 200 chars)
`url`	string	No	URL to associate with the event

Response — 201 Created

{
  "id": "a1b2c3d4-e5f6-...",
  "type": "signup",
  "name": "Sarah",
  "location": "Denver, CO",
  "created_at": "2025-01-15T10:30:00Z"
}

Error Responses

// 400 Bad Request
{ "error": "Invalid type" }

// 404 Not Found
{ "error": "Widget not found" }

// 429 Too Many Requests
{ "error": "Daily event limit reached" }

Backend Examples

Node.js

const res = await fetch('https://socialproof.tech/api/events', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    widgetId: 'YOUR_WIDGET_ID',
    type: 'purchase',
    name: 'Alex',
    message: 'Bought Pro Plan'
  })
});

const event = await res.json();
console.log('Created event:', event.id);

Python

import requests

res = requests.post('https://socialproof.tech/api/events', json={
    'widgetId': 'YOUR_WIDGET_ID',
    'type': 'purchase',
    'name': 'Alex',
    'message': 'Bought Pro Plan'
})

print('Created event:', res.json()['id'])

Event Types

Each event type produces a different notification style with its own icon and label.

Type	Icon	Label	Example	Plan
`signup`	🎉	NEW SIGNUP	Sarah from Denver just signed up	Free
`purchase`	💰	PURCHASE	Alex purchased Pro Plan	Free
`review`	⭐	REVIEW	Maria left a 5-star review	Free
`custom`	💬	ACTIVITY	New comment from James	Pro
`low_stock`	🔥	LOW STOCK	Only 3 left in stock!	Pro
`announcement`	📢	ANNOUNCEMENT	New feature: dark mode!	Pro
`urgency`	⏰	LIMITED TIME	Sale ends in 2 hours	Pro

Free plan supports signup, purchase, and review. Upgrade to Pro for all 7 types.

Configuration

Widget appearance is configured in your dashboard. Available settings:

Setting	Options	Default
Position	bottom-left, bottom-right, top-left, top-right	bottom-left
Theme	light, dark, auto	light
Display duration	2-15 seconds	5 seconds
Delay between	3-60 seconds	8 seconds
Border radius	0-24px	8px
Accent color	Any hex color	#4f46e5
Mobile position	bottom, top, hidden	bottom
Show timestamp	true / false	true
Show icon	true / false	true
Visitor count badge	true / false (Pro)	false

Shopify / Platforms without data-* support

If your platform doesn't support data-* attributes on script tags, pass the widget ID as a query parameter:

<script src="https://socialproof.tech/widget.js?widgetId=YOUR_WIDGET_ID"></script>

Need help?

Pro plan users get priority email support. Check your dashboard for embed code tailored to your widget.