Add JustOneCX to Open SaaS (Wasp)
Open SaaS is an open-source SaaS starter built on Wasp, React and Node. This guide names the files in its template/app folder (read on 2026-11-05, Wasp ^0.27.0). If your copy has moved files, find the same things by name.
What you need
- Your public key (starts with
pk_) from Settings → Developers. - Your site's origin in Settings → Developers → Domains & CORS, for example
http://localhost:3000for local work. See Allowed origins. - The npm package, added in the
appfolder:npm install @justonecx/sdk.
1. Add the public key as a client variable
Wasp client variables must start with REACT_APP_. Add the name to .env.client (copy .env.client.example if you do not have one):
REACT_APP_JUSTONECX_PUBLIC_KEY=pk_your_workspace_keyThen add it to the client schema in src/env.ts, next to the existing client variables:
export const clientEnvValidationSchema = defineEnvValidationSchema(
z.object({
...paddleClientEnvSchema.shape,
REACT_APP_JUSTONECX_PUBLIC_KEY: z.string().startsWith("pk_"),
}),
);Read it in client code with import { env } from "wasp/client".
2. Start the SDK in the root component
main.wasp.ts sets client.rootComponent to App in src/client/App.tsx. It wraps every page, so it is the right place. Add this inside App, before the return:
import { useEffect } from "react";
import { useAuth } from "wasp/client/auth";
import { env } from "wasp/client";
import { identify, init, reset } from "@justonecx/sdk";
// inside App():
const { data: user } = useAuth();
useEffect(() => {
void init({
publicKey: env.REACT_APP_JUSTONECX_PUBLIC_KEY,
apiUrl: "https://api.justonecx.com",
trackRouteChanges: true,
});
}, []);
useEffect(() => {
if (user) void identify(user.id);
else reset();
}, [user]);trackRouteChanges: true matters because Wasp uses client-side routing: the SDK needs it to check page targeting again after each navigation.
Use the field your User really has as the id (user.id in the template). Pass the same value every time.
3. Check it works
Open the app in a new window. The browser console logs every SDK problem with a [JustOneCX] prefix. Create a tour in the dashboard and publish it. If nothing shows, use the troubleshooting page.
4. Sign the user id on the server (identity verification)
Your public key is in the page, so anyone can call identify("someone-else"). Identity verification stops that: your server signs the user id and the SDK sends the signature.
Store the Secret key only in your server environment. Add the name to .env.server.example, add it to serverEnvValidationSchema in src/env.ts as JUSTONECX_SECRET_KEY: z.string().min(1), and paste the real value into your own .env.server or hosting dashboard yourself. Never give it to an AI assistant or put it in code.
Follow the pattern in src/user/operations.ts and src/user/user.wasp.ts: write a query that returns the hash for the signed-in user, and register it with query(...).
// src/user/operations.ts
import { createHmac } from "node:crypto";
import { HttpError, env } from "wasp/server";
export const getJustOneCXHash = async (_args: void, context: { user?: { id: string } }) => {
if (!context.user) throw new HttpError(401, "Sign in first");
return createHmac("sha256", env.JUSTONECX_SECRET_KEY).update(context.user.id).digest("hex");
};Add it to the spec in src/user/user.wasp.ts with query(getJustOneCXHash, { entities: [] }), as the file already does for getPaginatedUsers. Check the exact types and the entities option against the Wasp docs for your version.
In App.tsx, call it with useQuery from wasp/client/operations, then pass the result:
void identify(user.id, undefined, { userHash });Sign exactly the same string you pass to identify().
Order matters. Deploy the hash first and check that sign-ins verify. Only then turn on Require identity verification in Settings → Developers. If you turn it on before your live site sends the hash, all existing users count as unverified.
5. Ask your AI assistant to do it
Open SaaS ships an AGENTS.md and a CLAUDE.md, so a coding assistant already knows the repo. If it is connected to the MCP server, ask it: "Add JustOneCX to this Wasp app." It can add the component code and save a first tour as a draft. It never sees your Secret key.
What next
- Product tours and targeting
- Next.js SaaS boilerplates for other starters
- Server events to send events your server can vouch for