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/recapt.js?key=YOUR_API_KEY"
  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 with your API key as ?key= query parameter
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/recapt.js?key=pk_live_abc123..."
      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, create a component that loads the Recapt script. The SDK auto-initializes from the script URL.

Create a RecaptSetup.tsx component:

"use client";

import { useEffect } from "react";

export function RecaptSetup() {
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://cdn.recapt.app/browser/recapt.js?key=YOUR_API_KEY";
    script.async = true;
    script.setAttribute("data-public-key", "YOUR_API_KEY");
    script.setAttribute("data-persist", "");
    document.head.appendChild(script);
  }, []);

  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​

To associate sessions with your users, wait for the SDK to be ready and then call recapt("identify", ...):

"use client";

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

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

export function RecaptSetup() {
  const { user, isLoading } = useAuth();
  const scriptLoaded = useRef(false);

  useEffect(() => {
    if (scriptLoaded.current) return;
    scriptLoaded.current = true;

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

  useEffect(() => {
    if (isLoading || !user) return;

    const identify = () => {
      if (!window.Recapt) {
        setTimeout(identify, 100);
        return;
      }
      window.recapt("identify", {
        uid: user.id,
        email: user.email,
        nickname: user.nickname,
      });
    };

    identify();
  }, [user, isLoading]);

  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/recapt.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/recapt.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​