Racoons Docs
Guides

Integration Guide

Learn how to sign up for Racoons and integrate it into your web application.

Getting Started with Racoons

This guide will walk you through signing up for Racoons and integrating it into your web application to start collecting data.

Sign Up

  1. Visit the Racoons website and click "Sign In"
  2. Create your account using your email or sign in with a social provider

Create an Organization

After signing up, you'll be guided through creating your first organization:

  1. Enter your organization name
  2. Click "Submit"

Create a Project

Once your organization is set up, you'll be asked to create your first project:

  1. Click "New Project" or follow the onboarding flow
  2. Enter your project details:
    • Organization
    • Project name
    • Project URL
    • Project goal
  3. Click "Submit"

Install the Metrics Script

After creating your project, navigate to your project's settings page to find your unique integration code.

Installation

Copy the script block provided in your project settings and paste it into the <head> section of your web application:

<script type="module">
  import { initializeRacoons } from "https://cdn.racoons.ai/libs/index.mjs";
  initializeRacoons("<project-id>", { debugMode: false });
</script>

Important: Replace the project ID in the example above with your actual project ID from your settings page.

Configuration

The initializeRacoons() function accepts two parameters:

Parameters

  1. projectId (string, required)

    • Your unique project identifier
    • Found in your project settings page
    • Example: "9505de74-2e4f-4529-962b-781a4a13c4bb"

  2. options (object, required)

    • debugMode (boolean)
      • When true: Logs all events to the browser console before sending
      • When false: Sends events without console logging
      • Recommended: Use true during development, false in production

Example Configurations

Production Setup

initializeRacoons("<project-id>", { debugMode: false });

Development Setup

initializeRacoons("<project-id>", { debugMode: true });

Next.js Setup

<Script
  id="racoons-module"
  type="module"
  strategy="afterInteractive"
  dangerouslySetInnerHTML={{
    __html: `
                import { initializeRacoons }
                  from "https://cdn.racoons.ai/libs/index.mjs";
                initializeRacoons(
                  "<project-id>",
                  { debugMode: false }
                );
              `,
  }}
/>

Custom Event Tracking

In addition to automatic event tracking (page loads and clicks), Racoons allows you to track custom events with your own properties. This is useful for tracking specific user actions like button clicks, form submissions, purchases, or any other events important to your business.

Using trackEvent()

The trackEvent() function allows you to send custom events with optional properties:

import {
  initializeRacoons,
  trackEvent,
} from "https://cdn.racoons.ai/libs/index.mjs";

// Initialize first
initializeRacoons("<project-id>", { debugMode: false });

// Track a simple event
trackEvent("button_click");

// Track an event with properties
trackEvent("purchase_complete", {
  product_id: "abc123",
  price: 29.99,
  currency: "USD",
  category: "subscription",
});

Parameters

The trackEvent() function accepts two parameters:

  1. type (string, required)

    • The name or type of the event
    • Examples: "button_click", "form_submit", "purchase_complete", "modal_open"
    • Use descriptive names that clearly identify the action

  2. properties (object, optional)

    • Custom data to attach to the event
    • Must be JSON-serializable (objects, arrays, strings, numbers, booleans)
    • Cannot contain functions, DOM nodes, or circular references
    • Maximum size: 100KB per event

Automatic Enrichment

Custom events are automatically enriched with the same data as automatic events.

This means you don't need to manually track context information - it's all included automatically.

Example Use Cases

E-commerce Purchase

trackEvent("purchase_complete", {
  order_id: "ORD-12345",
  total: 149.99,
  currency: "USD",
  items: [
    { id: "PROD-1", name: "Widget", quantity: 2, price: 49.99 },
    { id: "PROD-2", name: "Gadget", quantity: 1, price: 49.99 },
  ],
  payment_method: "credit_card",
  shipping_method: "express",
});

Form Submission

trackEvent("form_submit", {
  form_name: "contact_form",
  form_fields: ["name", "email", "message"],
  submission_time_seconds: 45,
});

Feature Usage

trackEvent("feature_used", {
  feature_name: "export_data",
  format: "csv",
  row_count: 1500,
});

User Signup

trackEvent("user_signup", {
  signup_method: "google_oauth",
  plan: "pro",
  trial_days: 14,
});

Viewing Custom Events

Custom events appear in your Racoons dashboard alongside automatic events:

  1. Navigate to your project
  2. Click on the "Events" tab
  3. Click the "Columns" dropdown
  4. Enable the "Custom Properties" column
  5. Custom event properties will be displayed as JSON

You can filter, analyze, and visualize custom events just like automatic events.

Best Practices

  1. Use consistent naming conventions: Choose a naming pattern for event types (e.g., snake_case, camelCase) and stick to it
  2. Keep properties focused: Only include relevant data for each event
  3. Use structured data: Organize related properties into nested objects
  4. Avoid sensitive data: Don't track passwords, credit card numbers, or PII without proper handling
  5. Test in debug mode: Use debugMode: true during development to see events in the console before they're sent

Error Handling

The trackEvent() function includes built-in error handling:

  • If Racoons is not initialized, an error will be logged and the event won't be sent
  • If properties are not JSON-serializable, an error will be logged and the event won't be sent
  • If the server rejects the event (e.g., size limit exceeded), it will be logged in debug mode

Limitations

  • Maximum property size: 100KB per event
  • Properties must be JSON-serializable
  • Events count toward your subscription's usage limits (same as automatic events)

Verification

To verify your integration is working:

  1. Open your web application in a browser
  2. If using debugMode: true, open the browser console to see event logs
  3. Navigate through your application to trigger events
  4. If in production check your Racoons dashboard to confirm data is being received

Next Steps

Once your integration is complete and data is flowing:

  • Review your first page analysis in the Racoons dashboard
  • Set up team members and permissions
  • Use the chat to create charts and understand your data
  • Explore the MCP server for AI-powered insights (see MCP Server Guide)

Troubleshooting

Events not appearing in dashboard

  • Verify the project ID is correct
  • Check browser console for errors
  • Ensure the script is in the <head> section
  • Confirm your domain is authorized in project settings

Script loading errors

  • Verify you have internet connectivity
  • Check that https://cdn.racoons.ai is not blocked by ad blockers or firewalls
  • Ensure you're using the type="module" attribute in the script tag
  • Check that your project's Content Security Policy (CSP) is not blocking outbound requests to racoons.ai. You may need to add https://*.racoons.ai/ to your CSP.
    • The error will look something like this: Refused to connect to 'https://api.racoons.ai/events' because it violates the following Content Security Policy directive: "connect-src 'self'

Introduction

Racoons is a service that analyzes your website data with AI and gives you actionable ways to improve your metrics.

Shopify Integration

Set up Racoons analytics on your Shopify store in minutes using the Racoons AI Analytics app.

On this page

Getting Started with RacoonsSign UpCreate an OrganizationCreate a ProjectInstall the Metrics ScriptInstallationConfigurationParametersExample ConfigurationsProduction SetupDevelopment SetupNext.js SetupCustom Event TrackingUsing trackEvent()ParametersAutomatic EnrichmentExample Use CasesE-commerce PurchaseForm SubmissionFeature UsageUser SignupViewing Custom EventsBest PracticesError HandlingLimitationsVerificationNext StepsTroubleshootingEvents not appearing in dashboardScript loading errors