@thspian/circuul-react

Circuul helpers for React, Next.js, Vite, and CRA. Credits creators for web visits, or stamps a referral code on a landing page before an app install.

Before you install

1. On thspian.com, create a UGC campaign with Circuul CPA enabled (app_install or web_visit).
2. Copy your campaign app token — it starts with cat_….
3. Pass it to init({ appToken: 'cat_…' }).

The SDK talks to production Thspian automatically. You only need appToken.

Install

npm install @thspian/circuul-react

Peer dependency: react ≥ 17.

Web visit campaigns

import { useEffect } from 'react';
import { init } from '@thspian/circuul-react';

function App() {
  useEffect(() => {
    init({
      appToken: 'cat_…',
      kind: 'web_visit',
    }).then((result) => console.log('[Circuul]', result));
  }, []);

  return /* your app */;
}

Next.js

'use client';

import { useEffect } from 'react';
import { init } from '@thspian/circuul-react';

export default function Providers({ children }) {
  useEffect(() => {
    init({
      appToken: process.env.NEXT_PUBLIC_CIRCUUL_APP_TOKEN,
      kind: 'web_visit',
    });
  }, []);

  return children;
}

App install campaigns (web landing only)

Stores the referral code only — install CPA is credited when the native app opens.

init({
  appToken: 'cat_…',
  kind: 'app_install',
});

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | appToken | string | required | Campaign token from Thspian (cat_…) | | env | 'prod' \| 'dev' | 'prod' | Thspian API environment | | apiBase | string | from env | Explicit override — local/custom only | | kind | 'web_visit' \| 'app_install' | 'web_visit' | Campaign type | | autoConfirm | boolean | true | Skip API call when false (web_visit only) | | search | string | window.location.search | Override query string |

Dev

init({
  appToken: 'cat_…',
  env: 'dev',
  kind: 'web_visit',
});

Related

• @thspian/circuul-core
• @thspian/circuul-react-native

Create campaigns: thspian.com