Nudgg SDK Documentation

Everything a developer needs to self-serve an integration — and everything a CMO, security reviewer, or product lead needs to trust it.

Auto-capture readyPrivacy controlsLightweight SDK
Get startedView SDK reference
OverviewQuick startSDK ReferenceAuto-capture & privacyOn-site campaignsPerformance & securityTroubleshootingFAQ

Overview

What Nudgg SDK is, in plain terms

Nudgg SDK is a browser SDK that captures safe product signals, connects anonymous and known users, and powers AI-driven growth insights, segments, and campaigns.

01

Captures page views, sessions, and safe product signals

02

Optionally captures click metadata when enabled in workspace settings

03

Lets teams identify users and track custom events

04

Powers AI suggestions, segments, funnels, and onsite campaigns

Quick start

The fastest path to your first event

Two steps. Everything else on this page is optional depth.

1. Add the script

html
<script async src="https://www.nudgg.ai/nudgg_sdk/v1/nudgg_sdk.js"></script>
<script>
  window.nudgg.init({
    projectId: "YOUR_APP_ID"
  });
</script>

For React/Vite/SPAs, load the script once at app root and call init once.

2. Verify it's working

Open DevTools → Console and run:

console
window.nudgg
// → { init, track, identifyUser, updateProfile, logout, dispose, setIsDebug, version }

Integration checklist

Required

  • Add the SDK script
  • Call init({ projectId })
  • Verify events in the dashboard

Recommended

  • Call identifyUser() after login or signup
  • Track key business events with track()
  • Mark checkout, payment, login, and support forms private
  • Review events in the dashboard

Developers

SDK Reference

Every method lives on the global window.nudgg object once the script loads. Calls made before init() are queued in memory and replayed automatically.

window.nudgg.init(options)Required

Boots the SDK. Call it once, right after the script loads. Page views and session context are captured automatically from this point on — no extra call needed.

js
window.nudgg.init({
  projectId: "YOUR_APP_ID" // required — everything else is optional
});
ParameterDescription
projectId
stringRequired
Your workspace App ID, from Settings → Overview → SDK connection.
debug
boolean
Prints SDK activity to the console. Default: false.
runtimeSyncIntervalMs
number
Optional refresh interval for rules/campaigns/workspace settings, in ms. Default: 0, so periodic /v1/config polling is disabled. Positive values are clamped to at least 5 minutes.
maxEventBytes
number
Maximum serialized size of a single event before it's dropped client-side. Default: 24 KB.
maxBatchBytes
number
Maximum serialized size of one batched request. Default: 60 KB.
nonce
string
CSP nonce applied to dynamically injected optional-chunk scripts.

Click capture, semantic click context, and campaigns are controlled from workspace settings in the Nudgg dashboard — not from init() options.

window.nudgg.track(name, attributes?)

Use track() for business milestones, not raw UI interactions — events the SDK can't infer automatically.

js
window.nudgg.track("user_signed_up");

window.nudgg.track("purchase_completed", {
  plan: "pro",
  amount: 99,
  currency: "USD"
});

window.nudgg.track("checkout_started", { step: "cart" });
window.nudgg.track("demo_requested", { source: "pricing_page" });
ParameterDescription
name
stringRequired
Event name. Use snake_case, e.g. checkout_started.
attributes
Record<string, unknown>
Optional key-value pairs. Must be JSON-serializable.

Page views are captured automatically. You do not need to manually call track("page_view").

window.nudgg.identifyUser(userId, traits?)

Links the current anonymous visitor to a known user. Every visitor starts anonymous until this is called.

js
window.nudgg.identifyUser("usr_12345", {
  plan: "pro",
  role: "admin"
});
ParameterDescription
userId
stringRequired
A stable internal ID — database ID or UUID.
traits
Record<string, unknown>
Optional non-sensitive traits, e.g. plan, role, accountType.

Call this after login, signup, or whenever your app knows the visitor.

window.nudgg.updateProfile(traits)

Updates traits for an already-identified user without re-linking identity. Use for a plan upgrade, role change, or lifecycle-stage update.

js
window.nudgg.updateProfile({
  plan: "enterprise",
  seats: 25,
  lifecycleStage: "expansion"
});

Call updateProfile() only after identifyUser() has linked the visitor.

window.nudgg.logout()

Clears the current identity and starts a new anonymous session.

js
window.nudgg.logout();

Utilities

  • window.nudgg.dispose()

    Tears down listeners, timers, and campaign runtime. Useful for tests or embedded teardown.

  • window.nudgg.setIsDebug(value)

    Toggles console logging at runtime. Accepts booleans plus truthy strings like "true", "1", or "on".

  • window.nudgg.version

    Read-only SDK version string.

Data capture

Auto-capture & privacy

What's captured, what isn't, and how to exclude sensitive sections.

Auto-captured
  • site_visit
  • page_view
  • SPA route changes (pushState, replaceState, popstate, hashchange)
  • Allowed UTM / ad-attribution query parameters
  • Safe page, session, and browser context
Captured only when enabled
  • Click metadata, once a workspace admin turns it on
  • Safe clickable element label
  • Element tag and role
  • Click coordinates
  • Page context

Never captured

  • Password values
  • OTP values
  • Payment, card, and CVV values
  • Input, textarea, and select values
  • Full page text
  • Non-allowlisted query parameters
  • Content inside private / no-track regions

Exclude sensitive regions

Add any of these attributes to an element, or a wrapping ancestor, to exclude it from click capture:

data-privatedata-no-trackdata-nudgg-privatedata-nudgg-no-track
html
<form data-private>
  <input type="password" name="password" />
  <input type="text" name="verification_code" />
  <button type="submit">Verify</button>
</form>
  • Clicks inside private regions are not auto-captured.
  • For checkout, payment, login, and support flows, mark the full section private.
  • Send an explicit, safe custom event with track() instead.
safe custom event
window.nudgg.track("checkout_started", {
  step: "payment",
  cartValue: 149
});

Data capture

On-site campaigns

An optional layer on top of core analytics.

01

Optional — nothing renders unless the backend explicitly returns a decision.

02

The backend is authoritative for eligibility, frequency capping, suppression, and campaign rules.

03

The SDK records lifecycle events: impression, click, dismiss, and CTA click.

04

The campaign chunk loads only when the workspace actually has campaigns configured.

Trust

Performance & security

What to tell a CMO or security reviewer before approving a new script tag.

  • Loads asynchronously — never blocks page rendering.
  • Batches events — every 30s, once 30 events queue up, or when the tab is hidden.
  • Retries safely — exponential backoff for transient failures, up to 60s between attempts.
  • Uses beacon delivery on page unload for a best-effort final flush.
  • Campaign chunk loads only when needed — core analytics never waits for it.
  • Can be disabled remotely via a server-side kill switch.
  • CSP nonce supported for dynamically injected chunk scripts.
  • Only a public projectId (App ID) is exposed in the browser — no secret key.
  • localStorage holds only operational identity/session state — never profile, traits, or event content.

Trust

Troubleshooting

Practical fixes, organized by symptom.

I don't see events in the dashboard

  • Script loaded — check the Network tab for a 200 on the SDK script.
  • Correct projectId (App ID) passed to init().
  • Domain is allowlisted for the workspace.
  • init() is called after the script loads, not before.
  • Network tab shows requests to api.nudgg.ai.
  • Check that ad blockers or privacy extensions are not blocking the SDK script or API request.
  • Wait up to 60 seconds — events are batched before delivery.
console (debug: true)
// With debug: true, a successful boot logs, in order:
[Nudgg] Runtime bootstrap ready { host, ruleCount, serverTime, configVersion }
[Nudgg] Nudgg_SDK initialized

// Every captured action then logs individually:
[Nudgg] Action Tracked { name: "page_view", ... }

Clicks are not captured

  • Click capture is enabled in workspace settings.
  • The element is actually clickable (link, button, recognized ARIA role, or data-clickable).
  • It isn't inside a data-private / data-no-track region.
  • If runtime sync is disabled (default), reload the page after enabling click capture; otherwise wait for runtimeSyncIntervalMs.
  • The click text isn't being filtered for looking sensitive.

Campaign is not showing

  • The campaign is active for the workspace.
  • Campaign trigger rules match the visitor's activity.
  • The backend's decision response actually allows the campaign to render.
  • A frequency cap or suppression rule hasn't blocked it.
  • The campaign isn't unintentionally inside a private region.

SDK blocked by CSP

If the console shows a CSP violation for the SDK script or api.nudgg.ai, your Content-Security-Policy isn't allowlisting them yet — see "What CSP entries are required?" under Performance & security for the exact entries.

Common init mistakes

  • Calling init() before the script has loaded.
  • Wrong projectId (App ID).
  • Domain not allowlisted for the workspace.
  • Expecting instant capture instead of batched delivery.
  • CSP blocking the script or the API host.

Expected network calls

All requests go to api.nudgg.ai.

EndpointDetails
POST/v1/init

Immediately on init().

Bootstraps the runtime — domain check, rules, campaigns, workspace SDK settings.

POST/v1/session/start

On init, when no active session exists yet (or the previous one expired).

Opens a new session.

POST/v1/action/capture

Batched — every 30s, once 30 events queue up, or when the tab is hidden.

Delivers page views, clicks, and custom events.

POST/v1/identity/identify

After identifyUser() or updateProfile().

Links the visitor to a known user ID and traits.

POST/v1/identity/logout

After logout(), or when identifyUser() switches to a different userId.

Clears server-side identity linkage for the ending session.

POST/v1/session/end

On logout, user switch, or session expiry (30 min of inactivity).

Closes the session.

POST/v1/config

Only when runtimeSyncIntervalMs is set above 0. Disabled by default; positive values are clamped to at least 5 minutes.

Refreshes rules, campaigns, and workspace SDK settings without a page reload.

POST/v1/decision/trigger

Only if the workspace has campaigns, when a trigger condition matches an event.

Asks the backend whether an on-site campaign is eligible to render.

Other issues

Requests blocked by ad blockers or privacy extensions

Expected for a minority of sessions and not an SDK bug — retries succeed once the request is unblocked.

Duplicate page views

Usually another script (often a router library) is also patching history.pushState — check debug logs for a re-patch warning.

Trust

FAQ

Quick answers for marketing, security, and engineering stakeholders.

Still stuck?
Send your projectId (App ID), website URL, and a screenshot of your Network tab to the Nudgg team so we can debug the integration quickly.
Contact supportOpen dashboard