vTilt
By roleFoundersKnow what to fix firstMarketersSee what happens after the clickCMOsSee what your budget really buys
By businessSaaSTurn signups into active usersEcommerceSee why shoppers abandon cartsAgenciesProve your work to clientsEnterpriseOne customer record for every team
MeasureWeb AnalyticsFind where buyers leaveSession ReplaySee why they left, not just that they didAdsKnow what paid visitors do nextIntegrationsOne snippet feeds your stack
ThinkPeopleOne profile per customerCustomer MemoryvTilt remembers every visitorSite KnowledgeAnswers and audits from your own pages
ActAsk AIAnswers from real behaviorAI ChatChat that knows the visitorEmail CampaignsEmail from real visits
PricingWhy vTiltDocs
Docs / Initialize the SDK
Getting Started
OverviewInstallInitializeIdentify usersTrack eventsLogout & resetVerify eventsCommon mistakes
Guides
Event forwardingReverse proxyRealtime dashboardSite knowledge
Frontend frameworks
Next.jsNuxt.jsVue.jsReactReact RouterRemixGatsbySvelte / SvelteKitAstroAngularTanStack StartDocusaurus
Backend frameworks
NestJSHonoCloudflare WorkersDjangoFlaskLaravelPhoenixRuby on Rails
Backend languages
PythonPHPRubyElixirGoJava.NET / C#Rust
Stack guides
Vue + PHP
API Reference
Browser SDK
Script bundlesAutocaptureWeb VitalsSession recordingChat widgetFeature readinessRemote configurationDebug logging
Node SDK
Install & setupCapture, identify & aliasContext & shutdownGlobal properties & opt-outError tracking
MCP server
Guides
OverviewAuthenticationOAuthAgent skills (prompts)AI intelligenceSite knowledgeGoogle AdsMeta Ads
Client setup
CursorClaude DesktopVS CodeCodex

Getting Started

OverviewInstallInitializeIdentify usersTrack eventsLogout & resetVerify eventsCommon mistakes

Guides

Event forwardingReverse proxyRealtime dashboardSite knowledge

API Reference

MCP server

On this page

On this page

  • Inline script
  • npm / pnpm
  • Recommended init options
  • Update config at runtime
  • Next steps
DocsGetting StartedInitialize

Initialize the SDK

Last updated July 22, 2026

Call vt.init() once with your project token and recommended options. Run as early as possible in the page lifecycle.

Call vt.init() once with your project token. Run it as early as possible — in the inline script block, beforeInteractive in Next.js, or your app entry before paint. Calls before init() are no-ops; calls after queue until the SDK boots.

#Inline script

Add vt.init() in the same <script> block as the stub (or immediately after it):

<script>
  /* … stub loader … */
  vt.init('YOUR_PROJECT_TOKEN', {
    api_host: 'https://www.vtilt.com',
    autocapture: true,
    capture_pageview: true,
    capture_pageleave: true,
    persistence: 'localStorage',
  })
</script>
html

#npm / pnpm

import { vt } from '@v-tilt/browser'

vt.init('YOUR_PROJECT_TOKEN', {
  api_host: 'https://www.vtilt.com',
  autocapture: true,
  capture_pageview: true,
  capture_pageleave: true,
  persistence: 'localStorage',
})

// Optional: expose globally so window.vt examples in these docs work as-is
if (typeof window !== 'undefined') window.vt = vt
typescript

Note

With the npm package the SDK is the imported vt; window.vt is only set by the inline script stub. Either call methods on the import (vt.identify(...)) or assign window.vt = vt once, as shown above.

Note

Only the project token is required (from your vTilt dashboard). api_host is optional: most integrators on managed cloud use https://www.vtilt.com. If you self-host or use a reverse proxy, point api_host at your origin. Omit it to send events to the current page origin via relative URLs.

The default snippet loads array.js (core only). Chat and session recording lazy-load separate files — see Script bundles.

#Recommended init options

OptionRequiredTypical valueWhy you might change it
autocapturenotrueDisable for highly custom event tracking; pass an object to scope what's captured.
capture_pageviewnotrueDisable when you handle pageviews manually (e.g. exotic SPA frameworks).
capture_pageleavenotrue$pageleave events power engagement metrics — keep on unless you have a reason to drop them.
persistencenolocalStorageUse cookie for cross-subdomain identity, or memory to disable client-side persistence.
api_hostnohttps://www.vtilt.comReplace with your own origin if you reverse-proxy or self-host; omit for same-origin relative URLs.

#Update config at runtime

vt.updateConfig(patch) changes SDK settings after init(). Top-level keys shallow-merge; nested chat deep-merges.

vt.updateConfig({ autocapture: false })

vt.updateConfig({
  chat: {
    bubble: { offset: { bottom: 88, right: 24 } },
  },
})
typescript

See Chat widget and Remote configuration for feature-specific options.

#Next steps

  1. Identify users on every authenticated page load — not only at login.
  2. Track events with vt.capture() for domain actions.
  3. Verify events in Debug View.
PreviousInstallGetting StartedNextIdentify usersGetting Started