Getting Started

Get fluidsoul running in your app in three steps: install, send events, adapt your UI.

1. Install the SDK

npm install fluidsoul-js

2. Configure

Set these environment variables (never hardcode them):

FLUIDSOUL_API_URL=https://api.fluidsoul.dev  # or http://localhost:4000
FLUIDSOUL_API_TOKEN=your-api-token
FLUIDSOUL_WORKSPACE_ID=your-workspace-uuid

Create a config object:

import type { FluidsoulConfig } from "fluidsoul-js"

export const fluidsoulConfig: FluidsoulConfig = {
  apiUrl: process.env.FLUIDSOUL_API_URL!,
  token: process.env.FLUIDSOUL_API_TOKEN!,
  workspaceId: process.env.FLUIDSOUL_WORKSPACE_ID!,
}

3. Send events

Whenever a user does something meaningful, fire an event:

import { sendEvent } from "fluidsoul-js"

await sendEvent(fluidsoulConfig, {
  userId: "user_123",
  eventType: "report_viewed",
  metadata: { category: "analytics" },
})

4. Refresh context

After sending events (or at session boundaries), refresh the user's context:

import { refreshContext } from "fluidsoul-js"

await refreshContext(fluidsoulConfig, "user_123")

5. Read context and adapt

Fetch the computed context and use it to configure your UI:

import { getContext } from "fluidsoul-js"

const ctx = await getContext(fluidsoulConfig, "user_123")

if (ctx) {
  // ctx.user_category — e.g. "analyst", "executive", "hybrid"
  // ctx.feature_priorities — ordered list of features
  // ctx.recommended_defaults — suggested defaults for this user
  // ctx.engagement_level — "low" | "moderate" | "high"
  // ctx.user_maturity — "new" | "intermediate" | "power_user"
}

React quickstart

import { FluidsoulProvider, useFluidsoulContext } from "fluidsoul-js/react"

function App() {
  return (
    <FluidsoulProvider config={fluidsoulConfig}>
      <Dashboard />
    </FluidsoulProvider>
  )
}

function Dashboard() {
  const { context, loading } = useFluidsoulContext("user_123")

  if (loading) return <div>Loading...</div>
  if (!context) return <DefaultDashboard />

  return (
    <div>
      <h1>Welcome back</h1>
      <p>Category: {context.user_category}</p>
      <p>Top features: {context.feature_priorities.join(", ")}</p>
    </div>
  )
}

Next steps

Concepts — Understand how fluidsoul works
Configuring Rules — Set up custom dimensions and signals
API Reference — Full HTTP API docs
React Integration — Deep dive into React hooks

Getting Started

On this page