useArcy Hook

The useArcy hook gives you read access to session values from the ARCY SDK. Call it inside any component that is a descendant of ARCYProvider.

Usage

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

export function SessionDebug() {
  const { visitorId } = useArcy()
  return <p>Visitor: {visitorId}</p>
}

visitorId

visitorId: string | null

The stable anonymous ID the SDK assigns to this browser via localStorage. Persists across page loads until the user clears browser data.

Use this to link anonymous visitor behavior to a registered user at the moment of sign-in. Pass it to your backend's identify endpoint so ARCY can merge the pre-signup session history with the user's profile.

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

export function SignUpForm() {
  const { visitorId } = useArcy()

  async function handleSignUp(email: string, password: string) {
    await createAccount({ email, password, arcyVisitorId: visitorId ?? undefined })
  }

  // ...
}

Identity

User and organization identity is not set through useArcy. Pass userId, userTraits, organizationId, and organizationTraits directly as props to ARCYProvider at the root of your app.

<ARCYProvider
  publicKey={process.env.NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY!}
  userId={userId}
  userTraits={{ email: userEmail, plan: userPlan }}
  organizationId={orgId}
>
  {children}
</ARCYProvider>

See Configuration for all available props and quickstart prompts for framework-specific setup patterns.