Update and enhance SDK and Dashboard documentation.

google-labs-jules[bot] · google-labs-jules[bot] · commit c92f92144701 · 2025-06-19T08:45:14.000Z
This commit significantly revises and expands the documentation for the Databuddy SDK and Dashboard.

Key improvements include:

1.  **SDK Documentation (`sdk.mdx`):**
    *   Documented all `DatabuddyConfig` options from `types.ts`, including defaults and ranges.
    *   Added a comprehensive "SDK Methods Reference" for all programmatic SDK calls (`track`, `screenView`, `setGlobalProperties`, `clear`, `flush`, `trackError`).
    *   Created a "Standard Event Reference" detailing predefined events (`screen_view`, `page_exit`, `button_click`, etc.) and their properties.
    *   Thoroughly documented automatic event tracking via `data-track` and other `data-*` attributes.
    *   Updated the "Default Values Table" to be complete and accurate.
    *   Improved the `filter` configuration example.

2.  **Dashboard Documentation (`dashboard.mdx`):**
    *   Added new sections for "Funnel Analysis," "User Journey Visualization," and "User Profiles," explaining how to populate these features using SDK event tracking.
    *   Enhanced existing sections (Geo Analytics, Custom Events, Performance, Errors) with callouts clarifying necessary SDK configurations or event tracking methods.
    *   Added cross-links to relevant SDK documentation.

3.  **Consistency and Accuracy:**
    *   Standardized use of `clientId` and `NEXT_PUBLIC_DATABUDDY_CLIENT_ID` across all relevant files (especially `Integrations/nextjs.mdx`).
    *   Removed outdated "Last updated" dates from privacy and performance guides.
    *   Verified SDK versioning mentions (defaults to package.json version).
    *   Corrected code examples, including removing a non-existent `debug` prop from `nextjs.mdx`.

4.  **Getting Started &amp; Integration Guides:**
    *   Reviewed `getting-started.mdx` and `Integrations/nextjs.mdx` to ensure alignment with the detailed SDK documentation.
    *   Improved navigation links in `getting-started.mdx` to point to more specific sections in `sdk.mdx`.

These changes aim to provide you with clearer, more comprehensive, and accurate documentation, enabling you to better integrate and utilize Databuddy.
diff --git a/apps/docs/content/docs/Integrations/nextjs.mdx b/apps/docs/content/docs/Integrations/nextjs.mdx
@@ -38,7 +38,7 @@ export default function RootLayout({
     <html lang="en">
       <body>
         <Databuddy 
-          clientId={process.env.NEXT_PUBLIC_DATABUDDY_SITE_ID!}
+          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
           trackScreenViews={true}
           trackHashChanges={true}
           trackAttributes={true}
@@ -95,7 +95,7 @@ export default function RootLayout({
     <html lang="en">
       <body>
         <Databuddy 
-          clientId={process.env.NEXT_PUBLIC_DATABUDDY_SITE_ID!}
+          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
           trackScreenViews={true}
         />
         {children}
@@ -138,7 +138,7 @@ function MyApp({ Component, pageProps }: AppProps) {
   return (
     <>
       <Databuddy 
-        clientId={process.env.NEXT_PUBLIC_DATABUDDY_SITE_ID!}
+        clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
         trackScreenViews={true}
         trackAttributes={true}
       />
@@ -164,9 +164,9 @@ export default function Document() {
       <Head>
         <script
           src="https://app.databuddy.cc/databuddy.js"
-          data-client-id={process.env.NEXT_PUBLIC_DATABUDDY_SITE_ID}
+          data-client-id={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
           data-track-screen-views="true"
-          async
+          defer
         />
       </Head>
       <body>
@@ -183,13 +183,13 @@ export default function Document() {
 Add to your `.env.local`:
 
 ```tsx
-NEXT_PUBLIC_DATABUDDY_SITE_ID=your_site_id_here
+NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your_client_id_here
 ```
 
 For production, add to your deployment environment:
 
 ```tsx
-NEXT_PUBLIC_DATABUDDY_SITE_ID=your_production_site_id
+NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your_production_client_id
 ```
 
 ## Tracking Events
@@ -292,7 +292,7 @@ export default function RootLayout({
     <html lang="en">
       <body>
         <Databuddy 
-          clientId={process.env.NEXT_PUBLIC_DATABUDDY_SITE_ID!}
+          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
           // Core tracking
           trackScreenViews={true}
           trackHashChanges={true}
@@ -340,7 +340,7 @@ export default function RootLayout({
       <body>
         {process.env.NODE_ENV === 'production' && (
           <Databuddy 
-            clientId={process.env.NEXT_PUBLIC_DATABUDDY_SITE_ID!}
+            clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
             trackScreenViews={true}
             trackAttributes={true}
           />
@@ -369,28 +369,17 @@ import { Databuddy } from '@databuddy/sdk';
 ### Environment Variables on Vercel
 
 1. Go to your Vercel project settings
-2. Add environment variable: `NEXT_PUBLIC_DATABUDDY_SITE_ID`
+2. Add environment variable: `NEXT_PUBLIC_DATABUDDY_CLIENT_ID`
 3. Set different values for preview and production environments
 
 ## Troubleshooting
 
 ### Common Issues
 
-**Script Not Loading**: Ensure your environment variable `NEXT_PUBLIC_DATABUDDY_SITE_ID` is set correctly.
+**Script Not Loading**: Ensure your environment variable `NEXT_PUBLIC_DATABUDDY_CLIENT_ID` is set correctly.
 
 **Events Not Tracking**: Check browser console for any JavaScript errors and verify the Databuddy script is loaded.
 
 **Route Tracking**: If using custom route tracking, make sure the Analytics component is properly added to your layout.
 
-### Debug Mode
-
-Enable debug mode in development:
-
-```tsx
-<Databuddy 
-  clientId={process.env.NEXT_PUBLIC_DATABUDDY_SITE_ID!}
-  debug={process.env.NODE_ENV === 'development'}
-/>
-```
-
-Need help with your Next.js integration? Contact us at [help@databuddy.cc](mailto:help@databuddy.cc). 
+Need help with your Next.js integration? Contact us at [help@databuddy.cc](mailto:help@databuddy.cc).
diff --git a/apps/docs/content/docs/dashboard.mdx b/apps/docs/content/docs/dashboard.mdx
@@ -272,6 +272,10 @@ Discover your global audience and optimize for different regions:
 **Privacy Note**: Location data is derived from IP addresses and anonymized. No precise location tracking is performed.
 </Callout>
 
+<Callout type="tip" title="Powering the Map View">
+The geographic data displayed on maps and in regional breakdowns is typically derived from the user's IP address at the beginning of a session. This functionality is an integral part of session tracking. Ensure `trackSessions={true}` (which is enabled by default) in your [SDK configuration](/docs/sdk#-configuration-options) to collect this data.
+</Callout>
+
 ## 💻 Technology Stack Analysis
 
 Understand your audience's technical environment:
@@ -323,6 +327,10 @@ Understand your audience's technical environment:
 
 Track and analyze your business-specific events with detailed property breakdowns:
 
+<Callout type="info" title="Populating This Section">
+The analytics, breakdowns, and examples shown here are populated by the custom events you actively send from your application using the `db.track('your_event_name', {your_properties})` method. The more relevant and well-structured custom events you track, the more insightful this section will become. For detailed guidance on how to implement custom event tracking, please refer to the [SDK Methods Reference](/docs/sdk#-sdk-methods-reference) and strategies in the [Custom Event Tracking](/docs/sdk#-custom-event-tracking) section of the SDK documentation.
+</Callout>
+
 ### 📊 Enhanced Event Interface
 
 <Tabs items={['Hierarchical View', 'Property Breakdowns', 'Interactive Features']}>
@@ -500,6 +508,10 @@ Slice and dice your data for specific insights:
 
 Monitor your website's technical health and user experience:
 
+<Callout type="tip" title="Enabling Performance Data">
+The performance metrics, including Core Web Vitals, are populated when you enable `trackPerformance={true}` (enabled by default) and `trackWebVitals={true}` (disabled by default, but recommended) in your [SDK configuration](/docs/sdk#-optional-tracking-features). Enabling these options allows the SDK to collect detailed timing and performance data from the user's browser.
+</Callout>
+
 ### ⚡ Core Web Vitals
 
 <Tabs items={['Understanding Metrics', 'Performance Optimization']}>
@@ -575,6 +587,10 @@ Monitor your website's technical health and user experience:
 
 Monitor and resolve issues affecting your users:
 
+<Callout type="tip" title="Enabling Error Data Collection">
+To populate the error tracking sections of the dashboard, ensure you have `trackErrors={true}` enabled in your [SDK configuration](/docs/sdk#-optional-tracking-features). This will automatically capture unhandled JavaScript errors and promise rejections. For more detailed context on specific handled errors, you can manually send error events using `db.track('error', { /* custom properties */ })` as described in the [SDK Methods Reference](/docs/sdk#-sdk-methods-reference).
+</Callout>
+
 ### 🐛 JavaScript Error Analytics
 
 <Accordions>
@@ -759,4 +775,54 @@ Get your data where you need it:
 
 <Callout type="info">
 **Need Help?** Join our [Discord community](https://discord.gg/JTk7a38tCZ) or [contact support](mailto:support@databuddy.cc) for dashboard assistance.
-</Callout> 
+</Callout>
+
+---
+
+## 📊 Funnel Analysis
+
+Funnel analysis helps you understand how users progress through specific sequences of actions on your site, such as a signup process or a checkout flow. Defining and tracking these steps is crucial for identifying drop-off points and optimizing conversion rates.
+
+<Callout type="tip" title="Populating Funnel Data">
+To populate funnel data, you need to:
+1. Define the steps of your funnel within the Databuddy dashboard settings.
+2. Ensure each step corresponds to a custom event (or page view) that you are tracking with the SDK. For example, a signup funnel might be defined by a sequence of events like `viewed_signup_page` (a screen view), `started_signup_form` (custom event), and `completed_signup` (custom event).
+
+The sequence of these events for users will then build the funnel visualization. For more details on sending custom events, see the [SDK Methods Reference](/docs/sdk#-sdk-methods-reference) in the SDK documentation.
+</Callout>
+
+*(Detailed instructions on how to define funnels within the dashboard interface and interpret the funnel visualization will be available here. This feature helps pinpoint where users drop off in key workflows.)*
+
+---
+
+## 🗺️ User Journey Visualization
+
+User journey visualization allows you to see the paths users take through your website on a session-by-session basis. This includes the sequence of page views and custom events they trigger, offering insights into user behavior and navigation patterns.
+
+<Callout type="tip" title="Data for User Journeys">
+This feature relies on the comprehensive event data tracked by the SDK. The richness of the user journeys depends on:
+- Thorough `screen_view` tracking (often automatic via `trackScreenViews={true}` in the [SDK configuration](/docs/sdk#-configuration-options)).
+- Detailed custom event tracking (`db.track()`) for significant interactions as described in the [SDK Methods Reference](/docs/sdk#-sdk-methods-reference).
+
+Each event is tied to a user's session, allowing the dashboard to reconstruct their path.
+</Callout>
+
+*(Information on how to access and interpret user journey maps in the dashboard, including filtering by user segments or starting/ending events, will be detailed here. This helps understand common paths to conversion or points of confusion.)*
+
+---
+
+## 👤 User Profiles
+
+The dashboard can compile user profiles that show a history of activity for individual visitors, even if they are anonymous. These profiles are built by aggregating all events linked to the same unique user ID, which the SDK manages automatically as part of session tracking (`trackSessions={true}`).
+
+<Callout type="tip" title="Building Rich User Profiles">
+Richer user profiles are developed when you consistently track custom events that provide context about user actions and milestones. While the SDK handles user identification, the depth of each profile is determined by the quality and breadth of your event tracking strategy.
+
+Refer to these SDK documentation sections for more:
+- [Custom Event Tracking](/docs/sdk#-custom-event-tracking) for strategy.
+- [Standard Event Reference](/docs/sdk#-standard-event-reference) for common event types.
+- [SDK Methods Reference](/docs/sdk#-sdk-methods-reference) for `db.track()` and `db.setGlobalProperties()`.
+- The `db.setGlobalProperties()` method can be particularly useful for adding persistent attributes to a user's profile.
+</Callout>
+
+*(Details on where to find user profiles in the dashboard, what information they contain (e.g., event history, first seen, last seen, device info, location), and how to use them for segmentation or understanding individual user behavior will be provided here.)*
diff --git a/apps/docs/content/docs/getting-started.mdx b/apps/docs/content/docs/getting-started.mdx
@@ -93,8 +93,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
           clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
           trackScreenViews
           trackPerformance
-          trackWebVitals
-          trackErrors
+          trackWebVitals={true} // Default is false, explicitly enable for quick start
+          trackErrors={true}    // Default is false, explicitly enable for quick start
         />
         {children}
       </body>
@@ -359,14 +359,14 @@ window.pageLoadTime = Date.now();
 ## 🎉 What's Next?
 
 <Cards>
-  <Card title="SDK Reference" href="/docs/sdk" icon="📦">
-    Explore all configuration options and advanced features
+  <Card title="SDK Configuration Guide" href="/docs/sdk#-configuration-options" icon="📦">
+    Explore all SDK configuration props and options
   </Card>
   <Card title="Dashboard Guide" href="/docs/dashboard" icon="📊">
-    Learn to navigate your analytics dashboard
+    Learn to navigate your analytics dashboard and its features
   </Card>
-  <Card title="SDK Reference" href="/docs/sdk" icon="⚙️">
-    Set up custom events, performance monitoring, and more
+  <Card title="Event Tracking Deep Dive" href="/docs/sdk#-sdk-methods-reference" icon="⚙️">
+    Master custom event tracking, SDK methods, and standard event types
   </Card>
   <Card title="Security & Privacy" href="/docs/security" icon="🔒">
     Configure privacy settings and GDPR compliance
diff --git a/apps/docs/content/docs/performance/core-web-vitals-guide.mdx b/apps/docs/content/docs/performance/core-web-vitals-guide.mdx
@@ -512,6 +512,4 @@ Ready to optimize your Core Web Vitals? Databuddy provides built-in performance
 
 [Start monitoring your Core Web Vitals →](https://app.databuddy.cc/register)
 
----
-
-*Last updated: June 2025* 
+---
diff --git a/apps/docs/content/docs/privacy/cookieless-analytics-guide.mdx b/apps/docs/content/docs/privacy/cookieless-analytics-guide.mdx
@@ -525,6 +525,4 @@ Ready to go cookieless? Databuddy makes the transition simple and seamless.
 
 [Start your cookieless analytics journey →](https://app.databuddy.cc/register)
 
----
-
-*Last updated: June 2025* 
+---
diff --git a/apps/docs/content/docs/sdk.mdx b/apps/docs/content/docs/sdk.mdx
