Configuration

ARCYProvider is the root component that connects your app to ARCY. Wrap your root layout with it and pass your publishable key plus any identity props you have available.

Props

`publicKey` (required)

publicKey: string

Your ARCY publishable key. Safe to include in client-side code. Get it from app.arcyai.com under Settings > API Keys.

Store it in your env file and pass it via process.env or import.meta.env:

bash

NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY=pk_live_...

tsx

publicKey={process.env.NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY!}

bash

VITE_ARCY_PUBLISHABLE_KEY=pk_live_...

tsx

publicKey={import.meta.env.VITE_ARCY_PUBLISHABLE_KEY}

`userId`

userId?: string

Your auth system's user ID for the currently logged-in user. When passed, ARCY ties behavioral signals to this user in your dashboard. Pass undefined (not null) when no user is signed in.

`userTraits`

userTraits?: {
  email?: string
  name?: string
  plan?: string
  role?: string
  createdAt?: string | Date
  [key: string]: string | number | boolean | null | undefined | Date
}

Traits used for segmentation and ICP analytics. All fields are optional. More traits give ARCY more signal for behavioral analysis.

`organizationId`

organizationId?: string

Your auth system's organization or workspace ID. For B2B SaaS products. Links this user to an account in your ARCY dashboard.

`role`

role?: string

The user's role within the app (e.g. "admin", "viewer"). Used in the dashboard to segment sessions by role.

`metadata`

metadata?: Record<string, string | number | boolean | null>

Arbitrary session metadata attached to every event. Use for any dimensions not covered by userTraits.

Full example

tsx

"use client"
import { ARCYProvider } from "@arcyai/sdk/react"
import "@arcyai/sdk/styles"

interface ArcyWrapperProps {
  userId?: string | null
  userEmail?: string | null
  userPlan?: string | null
  organizationId?: string | null
  children: React.ReactNode
}

export function ArcyWrapper({
  userId,
  userEmail,
  userPlan,
  organizationId,
  children,
}: ArcyWrapperProps) {
  return (
    <ARCYProvider
      publicKey={process.env.NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY!}
      userId={userId ?? undefined}
      userTraits={
        userEmail
          ? { email: userEmail, plan: userPlan ?? undefined }
          : undefined
      }
      organizationId={organizationId ?? undefined}
    >
      {children}
    </ARCYProvider>
  )
}

How ARCYProvider receives identity

Pass userId and userTraits directly as props. The values should come from your auth system, read server-side (for Next.js App Router) or from a client auth hook (for Pages Router, Vite, or client-only setups).

Read identity server-side and pass it as props to a client wrapper:

app/layout.tsx

import { auth } from "@clerk/nextjs/server"
import { ArcyWrapper } from "@/components/arcy-wrapper"

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const { userId } = await auth()
  return (
    <html lang="en">
      <body>
        <ArcyWrapper userId={userId}>{children}</ArcyWrapper>
      </body>
    </html>
  )
}

Read identity from a client auth hook inside the wrapper:

tsx

import { useUser } from "@clerk/clerk-react"
import { ARCYProvider } from "@arcyai/sdk/react"

function ArcyWrapper({ children }: { children: React.ReactNode }) {
  const { user } = useUser()
  return (
    <ARCYProvider
      publicKey={import.meta.env.VITE_ARCY_PUBLISHABLE_KEY}
      userId={user?.id ?? undefined}
      userTraits={
        user?.primaryEmailAddress
          ? { email: user.primaryEmailAddress.emailAddress }
          : undefined
      }
    >
      {children}
    </ARCYProvider>
  )
}

See the quickstart prompts for complete patterns covering all auth libraries.