Skip to main content

Installation

This guide covers the complete installation process for Recapt using the script tag method.

Overview​

Installing Recapt is a simple three-step process:

  1. Generate your API key
  2. Configure allowed domains
  3. Add the script tag to your website

Step 1: Generate Your API Key​

  1. Log in to your Recapt dashboard
  2. Go to Installation in the sidebar
  3. Click Generate to create a new API key
  4. Your API key will be displayed - keep this safe
warning

If you regenerate your API key, your existing installation will stop working until you update the key in your website's code.

Step 2: Configure Allowed Domains​

For security, Recapt only accepts data from whitelisted domains.

  1. In the Installation wizard, go to Domain Settings
  2. Enter your domain (e.g., example.com)
  3. Click Add Domain
  4. Repeat for all domains and subdomains

Examples of domains to add:

  • example.com - Your main domain
  • www.example.com - WWW subdomain
  • app.example.com - Application subdomain
  • staging.example.com - Staging environment

Step 3: Add the Script​

Add this script tag to your website's <head> section:

<script
  src="https://cdn.recapt.app/browser/glimt.js"
  async
  data-public-key="YOUR_API_KEY"
  data-persist
></script>

Replace YOUR_API_KEY with the API key you generated in Step 1.

Script Attributes​

AttributeRequiredDescription
srcYesThe Recapt CDN URL
data-public-keyYesYour API key
data-persistNoKeeps sessions alive across page reloads
asyncNoLoads the script asynchronously (recommended)

Complete HTML Example​

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>My Website</title>

    <!-- Recapt Installation -->
    <script
      src="https://cdn.recapt.app/browser/glimt.js"
      async
      data-public-key="pk_live_abc123..."
      data-persist
    ></script>
  </head>
  <body>
    <!-- Your content -->
  </body>
</html>

Framework-Specific Examples​

React / Next.js (Recommended Approach)​

For React and Next.js applications, we recommend dynamically loading the Recapt script using a setup component. This gives you full control over initialization and user identification.

Create a RecaptSetup.tsx component:

"use client";

import { useEffect, useRef, useState } from "react";

// Extend Window interface for TypeScript
declare global {
  interface Window {
    Recapt: any;
    recapt: (action: string, data: any) => void;
  }
}

export default function RecaptSetup() {
  const [isScriptLoaded, setIsScriptLoaded] = useState(false);
  const retryCount = useRef(0);
  const maxRetries = 50; // 5 seconds total (50 * 100ms)

  // Load the Recapt script
  useEffect(() => {
    if (typeof window === "undefined") return;

    const script = document.createElement("script");
    script.src = "https://cdn.recapt.app/browser/glimt.js";
    script.async = true;

    // Configure via data attributes
    script.setAttribute("data-public-key", "YOUR_API_KEY");
    script.setAttribute("data-persist", "");

    script.onload = () => {
      setIsScriptLoaded(true);
    };

    script.onerror = () => {
      console.error("Failed to load Recapt script");
    };

    document.body.appendChild(script);

    return () => {
      try {
        document.body.removeChild(script);
      } catch (error) {
        // Script might already be removed
      }
    };
  }, []);

  // Wait for Recapt to be available, then identify user
  useEffect(() => {
    if (!isScriptLoaded) return;

    const waitForRecapt = () => {
      if (!window.Recapt) {
        if (retryCount.current < maxRetries) {
          retryCount.current++;
          setTimeout(waitForRecapt, 100);
        } else {
          console.warn("Recapt not available after 5 seconds");
        }
        return;
      }

      // Recapt is ready - identify your user here
      // Replace with your actual user data
      const user = getCurrentUser(); // Your auth logic

      if (user) {
        window.recapt("identify", {
          uid: user.id,
          email: user.email,
          nickname: user.nickname,
        });
      }
    };

    waitForRecapt();
  }, [isScriptLoaded]);

  return null;
}

Then include it in your app's root layout:

// app/layout.tsx (Next.js App Router)
import RecaptSetup from "@/components/RecaptSetup";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <RecaptSetup />
        {children}
      </body>
    </html>
  );
}

Identifying Users on Auth Changes​

To identify users when they log in or out, integrate with your auth provider:

"use client";

import { useEffect, useRef, useState } from "react";
import { useAuth } from "./your-auth-provider"; // Your auth hook

export default function RecaptSetup() {
  const { user, isLoading } = useAuth();
  const [isScriptLoaded, setIsScriptLoaded] = useState(false);
  const retryCount = useRef(0);
  const maxRetries = 50;

  // Load script effect (same as above)
  useEffect(() => {
    if (typeof window === "undefined") return;

    const script = document.createElement("script");
    script.src = "https://cdn.recapt.app/browser/glimt.js";
    script.async = true;
    script.setAttribute("data-public-key", "YOUR_API_KEY");
    script.setAttribute("data-persist", "");

    script.onload = () => setIsScriptLoaded(true);
    script.onerror = () => console.error("Failed to load Recapt script");

    document.body.appendChild(script);

    return () => {
      try {
        document.body.removeChild(script);
      } catch {}
    };
  }, []);

  // Identify user when auth state changes
  useEffect(() => {
    if (!isScriptLoaded || isLoading) return;

    const waitForRecapt = () => {
      if (!window.Recapt) {
        if (retryCount.current < maxRetries) {
          retryCount.current++;
          setTimeout(waitForRecapt, 100);
        }
        return;
      }

      retryCount.current = 0;

      if (user) {
        // User is logged in
        window.recapt("identify", {
          uid: user.id,
          email: user.email,
          nickname: user.nickname,
        });
      } else {
        // User logged out - clear identification
        window.recapt("identify", {
          uid: undefined,
          email: undefined,
          nickname: undefined,
        });
      }
    };

    waitForRecapt();
  }, [user, isLoading, isScriptLoaded]);

  return null;
}

Vue.js​

Add the script tag to your index.html:

<!-- public/index.html -->
<!DOCTYPE html>
<html>
  <head>
    <script
      src="https://cdn.recapt.app/browser/glimt.js"
      async
      data-public-key="YOUR_API_KEY"
      data-persist
    ></script>
  </head>
  <body>
    <div id="app"></div>
  </body>
</html>

Single Page Applications (SPAs)​

For SPAs, the data-persist attribute is important to maintain session continuity across route changes. The script automatically handles navigation events within your application.

tip

The dynamic script loading approach shown in the React/Next.js example above works well for any SPA framework. It ensures the script loads properly and gives you control over when to identify users.

Development Environment​

By default, Recapt won't record sessions from localhost. To enable recording during development:

  1. Go to Settings > Organization in your dashboard
  2. Toggle Localhost to enable
  3. Sessions from localhost will now be recorded
tip

We recommend keeping localhost disabled in production environments and only enabling it during active development.

Verifying Your Installation​

After installation, verify that Recapt is working:

  1. Check the browser console: You should not see any Recapt-related errors
  2. Visit your Recapt dashboard: Navigate to Sessions
  3. Look for your session: New sessions typically appear within 1-2 minutes

If you don't see sessions appearing, check:

  • Your API key is correct
  • Your domain is whitelisted
  • There are no JavaScript errors in the console

Troubleshooting​

Script Not Loading​

  1. Check that the script URL is correct: https://cdn.recapt.app/browser/glimt.js
  2. Verify there are no Content Security Policy (CSP) issues blocking the script
  3. Check your browser's Network tab for failed requests

Sessions Not Appearing​

  1. Verify your domain is in the whitelist
  2. Check that the API key matches your organization
  3. Ensure you're not on localhost (unless localhost is enabled)
  4. Wait a few minutes - sessions may take 1-2 minutes to appear

Console Errors​

If you see errors related to Recapt:

  1. Check that your API key is valid
  2. Verify the domain whitelist configuration
  3. Ensure the script is loaded before trying to use Recapt APIs

Next Steps​