Website Script

CampaignOS.js is a lightweight script you embed on your website to enable tracking, identification, push notifications, and personalization.

Installation

Add this script tag to your website:


<script
  src="https://your-campaignos-domain.com/campaignos.js"
  data-workspace="your-workspace-slug"
  data-uid="optional-user-id"
  async
></script>

Or load via URL parameters:


<script src="https://your-campaignos-domain.com/campaignos.js?workspace=your-slug&uid=user123" async></script>

Script Configuration Endpoint

`GET /api/script/config`

Returns personalization configuration for the embedded script.

Auth: None required

Query Parameters:

Param	Type	Required	Description
`workspace`	string	Yes	Workspace slug
`uid`	string	No	User identifier (externalId or identity)

Response:


{
  "workspaceId": "ws_abc123",
  "segments": ["seg_1", "seg_2"],
  "personalization": [],
  "pushEnabled": true
}

The script uses this response to:

Determine which segments the visitor belongs to
Apply personalization rules (modals, banners, toasts)
Enable/disable push notification prompts

Event Tracking Endpoint

`POST /api/script/event`

Tracks events from the website script.

Auth: None required

Request Body:


{
  "workspace": "your-workspace-slug",
  "type": "page_view",
  "uid": "user123",
  "metadata": {
    "title": "Pricing Page"
  },
  "sessionId": "sess_abc123",
  "pageUrl": "https://example.com/pricing",
  "referrer": "https://google.com",
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "summer-sale"
}

Field	Type	Required	Description
`workspace`	string	Yes	Workspace slug
`type`	string	Yes	Event type
`uid`	string	No	User identifier
`metadata`	object	No	Arbitrary event data
`sessionId`	string	No	Browser session ID
`pageUrl`	string	No	Current page URL
`referrer`	string	No	Referring URL
`utmSource`	string	No	UTM source
`utmMedium`	string	No	UTM medium
`utmCampaign`	string	No	UTM campaign

Response (201):


{ "id": "evt_abc123" }

What the Script Does

Tracking

Page views — Automatic on each navigation
Custom events — Via CampaignOS.track('event_type', { metadata })
UTM capture — Automatically extracts UTM parameters from URL

Identification

Resolves visitors by uid parameter (externalId or identity email)
Supports anonymous-to-known identity stitching when uid is provided later
Optional signed identity payloads for secure identification

Personalization

Fetches personalization rules from /api/script/config
Renders modals, banners, toasts, and embedded widgets
Targeting based on:
- Segment membership
- Event history
- Page path / referrer / UTM
- Frequency caps
Reports impressions, dismissals, and clicks as events

Push Notifications

Checks push permission status
Shows permission prompt (if enabled for workspace)
Registers push subscription with CampaignOS
Associates subscription with contact

JavaScript API


// Track a custom event
CampaignOS.track('purchase', {
  productId: 'prod_123',
  amount: 99.99
});
 
// Identify a user
CampaignOS.identify('user@example.com');
 
// Update user attributes
CampaignOS.setAttributes({
  plan: 'pro',
  company: 'Acme Inc.'
});

Service Worker

CampaignOS includes a service worker (cos-sw.js) for push notification handling. It is automatically registered by the script when push is enabled.