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.

It returns read values only. There are no identity methods to call: identity is set by passing userTraits and organizationTraits to ARCYProvider.

Usage

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

export function SessionDebug() {
  const { visitorId, sessionId, isReady, userId, organizationId } = useARCY()

  if (!isReady) return <p>Starting session...</p>

  return (
    <ul>
      <li>Visitor: {visitorId}</li>
      <li>Session: {sessionId}</li>
      <li>User: {userId ?? "anonymous"}</li>
      <li>Organization: {organizationId ?? "none"}</li>
    </ul>
  )
}

Return value

useARCY returns an ARCYSessionInfo object. Every field is a read value.

interface ARCYSessionInfo {
  visitorId: string | null
  sessionId: string | null
  isReady: boolean
  userId: string | null
  organizationId: string | null
}

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. null until the SDK has mounted.

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 })
  }

  // ...
}

sessionId

sessionId: string | null

The current ARCY session ID. null until the session has finished bootstrapping. Useful for correlating client-side logs with a session in the ARCY Console.

isReady

isReady: boolean

true once a session exists, equivalent to Boolean(sessionId). Use it to wait for the SDK before reading session-dependent values.

userId

userId: string | null

A read-only echo of the userId you supplied to ARCYProvider through userTraits.userId. null when no user identity was passed. The hook returns this single identifier, not the full userTraits object, so arbitrary trait data is never exposed through client code.

organizationId

organizationId: string | null

A read-only echo of the organizationId you supplied to ARCYProvider through organizationTraits.organizationId. null when none was passed. As with userId, the full organizationTraits object is never returned.

Identity

Identity is not set through useARCY. Pass userTraits and organizationTraits directly as props to ARCYProvider at the root of your app. The hook then echoes back userId and organizationId for read-only use.

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

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