SDK Reference

Complete reference for the Veriform SDK and certificate service.

SDK Installation #

Basic Setup #

Add the SDK script with your API key:

<!-- Veriform SDK -->
<script
    src="https://cert.veriform.co/sdk.min.js"
    data-key="YOUR_API_KEY"
    defer
></script>

Script Attributes #

Attribute	Required	Description
`src`	Yes	SDK URL: `https://cert.veriform.co/sdk.min.js`
`data-key`	Yes	Your API key (`test_xxx` or `prod_xxx`)
`defer`	Recommended	Non-blocking script load

API Key Types #

Prefix	Environment	Cost	Retention
`test_`	Development	Free	7 days
`prod_`	Production	Per plan	Per plan

Get your API keys from the Dashboard.

With Cache Busting #

To ensure you always get the latest SDK version:

<script src="https://cert.veriform.co/sdk.min.js?v=2" data-key="YOUR_API_KEY" defer></script>

How It Works #

Page Load: SDK validates your API key and generates a unique certificate ID
Connection: Opens a WebSocket connection to the certificate server
Recording: The SDK captures all DOM mutations, mouse events, inputs, and scrolls
Streaming: Events are sent to the server in real-time via WebSocket
Save: On form submit, call veriformSave() to finalize the recording
Certificate: Server fetches IP geolocation and generates the certificate

Global Functions #

`window.veriformSave()` #

Saves the current recording and generates the certificate. Must be called before page navigation.

// Returns a Promise
await window.veriformSave();

Returns: Promise<void> — Resolves when save is complete, rejects on error.

Example:

form.addEventListener('submit', async (e) => {
  e.preventDefault();
  
  try {
    await window.veriformSave();
    // Recording saved, safe to redirect
    window.location.href = certUrl;
  } catch (err) {
    console.error('Failed to save:', err);
    // Still redirect - server may have received the data
    window.location.href = certUrl;
  }
});

`window.veriformReady()` #

Check if the SDK is connected and recording.

if (window.veriformReady()) {
  console.log('Veriform is recording');
}

Returns: boolean

`window.veriformCertUrl()` #

Get the certificate URL for the current session.

const url = window.veriformCertUrl();
// https://cert.veriform.co/view/pub_abc123...

Returns: string

`window.veriformRecId()` #

Get the unique recording ID for the current session.

const id = window.veriformRecId();
// pub_abc123...

Returns: string

`window.veriformApiKeyValid()` #

Check the API key validation status.

const status = window.veriformApiKeyValid();
// true = valid, false = invalid, null = still validating

Returns: boolean | null

Auto-populated Elements #

The SDK automatically populates elements with specific IDs:

Element ID	Value Set
`#recCertUrl`	Full certificate URL

Example:

<input type="hidden" id="recCertUrl" name="certificate_url">

After SDK loads, the value will be:

https://cert.veriform.co/view/pub_xYz123AbC...

Certificate Data #

Each certificate captures:

Session Info #

Field	Description
`recId`	Unique certificate ID
`startTs`	Session start timestamp
`endTs`	Session end timestamp
`url`	Page URL

User Info #

Field	Description
`ip`	Client IP address
`useragent`	Full user agent string

IP Geolocation (`ipInfo`) #

Field	Description
`continent`	Continent name
`country`	Country name
`countryCode`	ISO country code
`region`	Region/state code
`regionName`	Region/state name
`city`	City name
`district`	District (if available)
`zip`	Postal/ZIP code
`lat`	Latitude
`lon`	Longitude
`timezone`	Timezone (e.g., `America/New_York`)
`offset`	UTC offset in seconds
`currency`	Local currency code
`isp`	Internet Service Provider
`org`	Organization name
`as`	AS number and name
`asname`	AS name
`reverse`	Reverse DNS
`mobile`	`true` if mobile network
`proxy`	`true` if proxy/VPN detected
`hosting`	`true` if datacenter/hosting

Event Data #

Field	Description
`events`	Array of session events

Event Types #

The SDK captures these event types:

Type	Description
`FullSnapshot`	Initial DOM snapshot
`IncrementalSnapshot`	DOM mutations, mouse, input, scroll
`Meta`	Page metadata

Incremental Sources #

Source	Description
`Mutation`	DOM changes
`MouseMove`	Mouse position changes
`MouseInteraction`	Clicks, focus, blur
`Scroll`	Scroll position changes
`ViewportResize`	Window resize
`Input`	Text input changes

API Endpoints #

`GET /view/:id` #

View the certificate page (HTML).

Access Control:

pub_* IDs: Public access
Other IDs: Requires JWT authentication

`GET /get/:id` #

Get raw certificate data (JSON).

Response:

{
  "recId": "pub_abc123...",
  "startTs": 1732741234567,
  "endTs": 1732741289012,
  "url": "https://example.veriform.co/",
  "ip": "1.2.3.4",
  "useragent": "Mozilla/5.0...",
  "ipInfo": { ... },
  "events": [ ... ]
}

`GET /exists/:id` #

Check if a certificate exists.

Response: true or false

`GET /sdk.min.js` #

Get the SDK script. The server injects the client’s IP address into the script.

WebSocket Protocol #

The SDK communicates via WebSocket at wss://cert.veriform.co.

Connection #

wss://cert.veriform.co?recId={certificate_id}

Messages (Client → Server) #

Message	Description
`recId:{id}`	Set the recording ID
`ip:{ip}`	Client IP (injected by server)
`useragent:{ua}`	Browser user agent
`url:{url}`	Page URL
`save`	Save the recording
`{json}`	Session event data

Messages (Server → Client) #

Message	Description
`saved`	Recording saved successfully
`error:{msg}`	Error occurred

Best Practices #

Always Call `veriformSave()` #

The recording is saved on WebSocket disconnect, but calling veriformSave() ensures it completes before redirect:

// ❌ Bad - might redirect before save completes
window.location.href = certUrl;

// ✅ Good - waits for save
await window.veriformSave();
window.location.href = certUrl;

Store the Certificate URL #

Always store the recCertUrl with your lead data:

const lead = {
  email: form.email.value,
  phone: form.phone.value,
  certificateUrl: document.getElementById('recCertUrl').value
};

await saveToDatabase(lead);

Handle Errors Gracefully #

try {
  await window.veriformSave();
} catch (err) {
  // Log but don't block the user
  console.error('Veriform save failed:', err);
}
// Continue with form submission

Check for SDK Availability #

if (typeof window.veriformSave === 'function') {
  await window.veriformSave();
}