; } ``` In Next.js add `"use client"` at the top. In Vue, Svelte, Angular, Solid, Astro, Lit and the rest the pattern is the same: call `mountRoadmap`, `mountIdeas` or `mountChangelog` after mount and `destroy()` on unmount. ## Routing | `routing` | Behaviour | | --- | --- | | `"query"` (default) | The open idea lives in `?idea=slug`. Works on any page with no server setup. | | `"path"` | Uses real paths such as `/roadmap/add-zapier-integration`. Set `basePath` and add a catch-all route so a shared link reaches the same page. | | `"none"` | Keeps the state in memory only. | ```ts mountRoadmap(element, { routing: "path", basePath: "/roadmap" }); ``` On a static host, rewrite `/roadmap/*` to your roadmap page. The dashboard generates the rule for nginx, Netlify, Vercel and Cloudflare. ## Handle `mount*` returns `{ destroy(), navigate(slug | null), on(event, callback) }`. Events: `vote`, `submit`, `comment`, `react`, `navigate`. ## Content Security Policy The board loads a second script, `justonecx-boards.global.js`, from the same place as the SDK. If you use a strict CSP, allow that origin in `script-src`, or set `boardsUrl` in [`init`](/api/init). ## CMS and site builders WordPress, Webflow and Shopify: paste the HTML snippet from the dashboard into a custom code block. --- # Help center The Help center gives visitors answers before they wait for a person. It lives in the chat widget: when a visitor first opens the chat panel, they see tabs instead of an empty conversation. You manage it in the dashboard under **Chat → Help center**. You need no extra code. | Tab | What it shows | |---|---| | **Chat** | Opens a conversation with your team. | | **Help** | Your FAQs: a question list where each answer opens under it. | | **Articles** | Longer how-to pages, with a reader view. | | **Learn** | Product tours a visitor can start themselves. | A tab only shows when it has something to read. Help needs at least one published FAQ, Articles at least one published article, and Learn at least one tour that is offered and matches the visitor. If no tab besides Chat has content, the panel opens a conversation right away. Nothing is generated and no AI provider is called. ## FAQs Under **Chat → Help center → FAQs**, add a question and its answer, group them with an optional **Group**, put them in order and switch them on. Only published FAQs show in the widget. Answers support lists (`1. ` or `- `), **bold** and `http(s)` links. ## Articles Under **Chat → Help center → Articles**, write the article in the editor. Use **Preview** to check how it renders. A blank line starts a new paragraph. Each article gets a web address name (its slug) from its title when you create it, and that name never changes, so a link you shared keeps working. Only published articles show. ## Learn tab Open a tour in the builder, go to the **Settings** tab, **Launcher** section, and switch on **Offer this tour in the Learn tab**. You can set: - **Title** and **Short description** (the tour name is the default title). - **Start page**: a path like `/dashboard` or a full `http(s)` URL. The Learn tab lists a tour only to visitors the tour's [targeting](/guides/targeting) matches, and puts a tick next to tours they have finished. When a visitor clicks a tour: - On its start page (or when you set none), the chat panel closes and the tour starts. - On another page, the SDK goes to the start page and starts the tour there. ## Order and switches Under **Chat → Settings → Widget home**, turn the Help center off (the panel then opens a conversation right away), switch single tabs on or off, and move them up and down. The order you set is the order visitors see. Chat and the Help center are independent. With chat switched off and the Help center on, the widget still opens, but shows only the help tabs: no Chat tab, no "Chat with us" line and no message box. ## Search The search box looks through the question and answer of every published FAQ and the title and text of every published article. It is plain text matching, with title matches first. It shows on the Help and Articles tabs. ## What your team sees Every FAQ a visitor opens, every article they read, every search and every tour they start from the Learn tab is logged. When that visitor starts a conversation, your team sees the list next to the chat, so the first message does not need to repeat it. A visitor who identified on a second browser shows the first browser's activity too. Visitors can mark a FAQ or article **Was this helpful?** with 👍 or 👎. Your team sees the vote in the same list. ## A person is always one click away The **Chat** tab, the **Still need help? Chat with us** line under every view and typing in the message box all open a conversation. What the visitor typed is the first message. A visitor who has talked to a person once goes straight to their conversation on later visits. ## Permissions Reading needs **View chat** (or **View assigned chats**). Changing FAQs, articles and settings needs **Configure chat**. --- # Hosted pages Every workspace gets a hosted roadmap, ideas board and changelog. Nothing to install. ``` https://boards.justonecx.com//roadmap https://boards.justonecx.com//ideas https://boards.justonecx.com//changelog ``` Find the exact links, and the switch that turns the hosted page on or off, in **Roadmap & Changelog > Publish > On our hosted page**. ## Good to know - The server renders the pages, so search engines and link previews see the real content. - Each idea and changelog entry has its own link, for example `//ideas/add-zapier-integration`. - Public boards are indexable. Identified and private boards send `noindex` and are never cached. - When you also serve the boards on a [custom domain](/guides/custom-domain), the pages tell search engines the custom domain is the original. - The pages use your workspace Brand Kit (colours and shape). - Optional: turn on **Offer an RSS feed of the changelog** (Roadmap & Changelog, Publish, On our hosted page) to serve a feed at `//changelog/feed.xml`. It is off by default. ## Who is signed in A visitor on a hosted page is anonymous unless you link them with a [sign-on link](/guides/board-sign-on). --- # Identity verification ## What it is, in plain words Your Public key (`pk_…`) is in your site's code, so anyone who opens your site can read it. Without more, anyone can then call `identify("someone-else")` and write to that person's profile, chat history and feedback. Identity verification closes that gap. After a user signs in, **your server** signs their user id with your Secret key. JustOneCX checks the signature and ignores `identify()` calls that do not have a valid one. ## Why you set it up on your server Only a secret that never reaches the browser can prove who is signed in. That is why the Secret key must live in **your server's environment**, as `JUSTONECX_SECRET_KEY`. JustOneCX cannot place it there for you, and it must never go in browser code. You do this once per site. It is not per user and not per page. ## Set it up, in this order The order matters. If you turn on **Require** before your site sends the signature, all your existing users count as unverified. 1. **Copy the Secret key.** Open **Settings → Developers → Secret key**. The full key is shown only once. If you missed it, regenerate it and copy the new one. 2. **Store it on your server only**, as `JUSTONECX_SECRET_KEY` (hosting dashboard, server `.env`, or CI secret). Add the empty name `JUSTONECX_SECRET_KEY=` to `.env.example`. 3. **Sign the user id on your server** after login (code below), and send the result to the browser with the signed-in user, for example in your session payload. 4. **Pass it to the SDK** in the browser, and deploy. 5. **Switch on Require.** In **Settings → Developers → Identity verification**, turn on **Require identity verification**. 6. **Check it works.** Sign in on your site, then look at the setup checklist (or ask your AI assistant to run `workspace_status`). It should say verified sign-ins are arriving. ## Sign on your server The Secret key is the same key you use to [send events from your server](/guides/keys). One key, one place to rotate. ::: code-group ```js [Node.js] import { createHmac } from "node:crypto"; const userHash = createHmac("sha256", process.env.JUSTONECX_SECRET_KEY) .update(String(user.id)) .digest("hex"); ``` ```python [Python] import hmac, hashlib, os user_hash = hmac.new( os.environ["JUSTONECX_SECRET_KEY"].encode(), str(user.id).encode(), hashlib.sha256 ).hexdigest() ``` ```ruby [Ruby] require "openssl" user_hash = OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("JUSTONECX_SECRET_KEY"), user.id.to_s) ``` ```php [PHP] $userHash = hash_hmac('sha256', (string) $user->id, getenv('JUSTONECX_SECRET_KEY')); ``` ::: ## Pass it to the SDK ```ts identify(user.id, { plan: user.plan }, { userHash }); group(account.id, { plan: account.plan }, { accountHash }); ``` `accountHash` is the HMAC of the account id, computed the same way. Sign exactly the same string you pass to `identify()`. ## Set it up with an AI coding assistant If your assistant is connected to the [JustOneCX MCP server](/ai/), ask it: "Set up JustOneCX identity verification". It reads the exact steps from `get_install_info`, adds the server code and `.env.example` entry, and passes `userHash` to `identify()`. It never sees your Secret key, on purpose: you paste the key into your server environment yourself. It switches **Require** on only after your site sends `userHash` and you say yes, because that setting changes the live site. ## If it does not work | Symptom | Likely cause | |---|---| | Users show as unverified after you turned Require on | Your site does not send `userHash` yet, or it signs a different string than the user id it passes to `identify()` (a number vs a string, or an email vs an id). | | Every hash is rejected | You signed with the Public key (`pk_…`) instead of the Secret key. | | It worked, then stopped | The Secret key was rotated and the server still has the old one. | | The hash is computed in the browser | Do not. The Secret key would be public. Compute it on the server. | To test one hash, ask your assistant to verify a `userId` and the hash your server made. It tells you whether it matches, and never shows the expected value. ## Roadmap and changelog Identity verification also protects the boards. A private board only opens for a visitor whose identity was verified, and an unverified `userId` never counts. On a hosted page or custom domain use a [sign-on link](/guides/board-sign-on). ## What happens without a valid hash When verification is on, a call without a valid hash returns normally but is ignored. It cannot merge into another person's profile or change their traits. ## Rotating the Secret key Rotating the Secret key invalidates every hash you issued and every server event call that still uses the old key. Your server must use the new key for **both** event ingest and `userHash`. Copy the new key from the dashboard right after you rotate, deploy it, then check that identify calls verify. ## If you used a separate identity secret before Older workspaces had a second key, the identity secret. It still works until you rotate your Secret key, and the dashboard shows a banner while it does. After you rotate, only the Secret key is accepted. --- # Keys You use three credentials. Each has one job. | Credential | Where it goes | What it does | |---|---|---| | **Public key** | The browser: `init({ publicKey })` | Shows tours, announcements, surveys, chat and the Help center to your visitors. Safe to share. | | **Secret key** | Your own server only | Sends events from your backend ([server events](/api/server-events)) and signs each user id for [identity verification](/guides/identity-verification) (`userHash`). | | **Agent token** | Your AI tool | Lets Claude, ChatGPT, Cursor or another AI tool act for one person. Connecting through OAuth creates it for you. | You find the Public key and the Secret key under **Settings → Developers**. ## Public key Anyone can read it in your page source, so it only grants access to content you already published. It starts with `pk_`. If it leaks, add your site under [allowed origins](/guides/allowed-origins) so other websites cannot reuse it, or regenerate it (every embed then needs the new key). ## Secret key It starts with `sk_`. It belongs in your server environment, for example as `JUSTONECX_SECRET_KEY`. Never put it in client code, a mobile app or a public repository. - The full key is shown **once**, when you generate it. We store it only encrypted and as a hash. After that the dashboard shows its first characters. - **One key does two jobs.** It authenticates server-to-server event calls and it is the secret for `userHash`. If you rotate it, your server must use the new key for **both**. - Rotating it invalidates the old key immediately, in both places. - A leaked Secret key lets someone send fake events and forge user identities. Treat it like a password and rotate it if you think it leaked. Workspaces created before 2026-10-17 also had a separate **identity secret**. It still works until you rotate your Secret key, and the dashboard shows a banner while it does. Rotating the Secret key retires it. ## Agent token An agent token is per person, not per workspace. It has the same permissions as the person who made it, narrowed to what you allow. The easiest way is to connect your AI tool through the MCP server and approve it in the browser (OAuth). See [AI assistants](/ai/). --- # Multi-page tours One tour can walk a visitor across several pages. Each step can belong to its own page, the SDK saves where the visitor is, and the tour carries on after a page change, in another tab or on another device. ## Put a step on a page In the step's **Pages, targets and completion** section: - **Same page as the step before** (the default). Switch it off to give the step its own page rule: is exactly, starts with, contains, matches pattern (`*` is one path segment, `**` any depth) or regex. - **Button takes the visitor to**: a path or URL. When the next step is on another page, this step's button goes there. **Button text when it leads to another page** replaces the button label. Until the visitor is on a matching page, nothing shows. When they arrive, the tour continues from that step. Call `init()` on every page, or use `trackRouteChanges: true` in a single-page app, so the SDK can check again after each navigation. A multi-page tour that is interrupted by navigation is **paused**, not dismissed. Its place is saved. A tour with no per-step pages still counts a navigation away as dismissing it, as before. ## Progress is kept on the server The SDK saves the current step (and what happened on each step) for each person. That is what lets a tour resume after a reload, and it follows the person to another browser once they `identify()`. When a person returns after a while, the tour continues from where they stopped. To start one person over, use **Start one person over** in the tour's **Results** tab, or **Restart** next to a tour in a customer's **Insights** in the chat inbox. ## Find the element by text or role A tooltip can list more ways to find its element, tried in order after the selector: visible **text** (button, link, label or any element), an ARIA **role** with an accessible name, a `data-jcx` anchor, or a CSS selector. Text and role targets keep working when generated class names change. A tooltip needs at least one of: a selector, or one of these. ## Required steps and skip reasons Mark a step **Required**. When a visitor closes it, they pick a reason first (set the list in the tour's **Settings** tab, **Targeting** section, **Skip reasons**; defaults: Not relevant, Already done, Later). The reasons appear per step in **Results**. ## Results **Results** shows started, finished, finished with skips, abandoned (no activity for 7 days), the biggest drop-off (with its page), a per-step table (reached, skipped by reason, target missing, median time) and a split by any user trait you send with `identify()`, for example `plan`. --- # Payload CMS and other admin panels Admin panels such as Payload CMS are a good fit for tours: one login, many screens. This is what to set up. ## Where to put the code - **`init()`**: once, in the admin app's root client component (in Payload, a custom component registered as a provider or a `beforeDashboard` component). Use `trackRouteChanges: true`, because the admin is a single-page app and its screens change without a reload. - **`identify()`**: right after the signed-in user is known, with their id and traits (`role`, `email`). ```js import { init, identify } from "@justonecx/sdk"; void init({ publicKey: "pk_your_key", apiUrl: "https://api.justonecx.com", trackRouteChanges: true, excludePaths: ["/api/**"] }); identify(user.id, { email: user.email, role: user.role }); ``` ## Give elements stable anchors Payload's generated class names change between versions. Add a `data-jcx` attribute to the components you want to point at, in your own custom components: ```tsx Create new ``` Then point the tour at `[data-jcx="posts-create"]`. Elements you cannot edit (Payload's own buttons) can be found by their visible text or ARIA role instead: add a text or role target in the step. ## Keep the storefront out If the same app serves a public site and the admin, only the admin should show tours. Use `excludePaths` for the public paths, or `disableTours: true` where the SDK should not run tours at all. See [init](/api/init) and [Targeting](/guides/targeting#turn-the-sdk-off-on-some-pages). ## Live preview frames Payload's live preview renders your site in an iframe. Add `excludePaths` for the preview route, or `disableTours`, `disableAnnouncements` and `disableSurveys`, so the frame does not show widgets. A second copy of the SDK on a page logs a warning and stays inactive. --- # Roadmap, ideas and changelog Show customers what you are building, let them request and vote on ideas, and tell them what shipped. One setup, three ways to show it: - **On your website**, embedded in any page, plus an in-app **What's new** panel. See [Embed](/guides/embed-roadmap-changelog) and [What's new widget](/guides/whats-new-widget). - **On your own subdomain**, such as `roadmap.yourcompany.com`. See [Custom domain](/guides/custom-domain). - **On our hosted page** at `boards.justonecx.com//roadmap`. No code. See [Hosted pages](/guides/hosted-boards). All of them show the same content. You manage it in the dashboard under **Roadmap & Changelog**, and you turn each way on or off in its **Publish** tab. ## The three parts | Part | What visitors see | | --- | --- | | Roadmap | Ideas grouped by status: planned, in progress, shipped. | | Ideas | Ideas with votes and comments. Visitors can submit new ones. | | Changelog | The entries you published, newest first. Visitors can mark an entry helpful. | ## From idea to changelog 1. A customer submits an idea, or you add one yourself. 2. You move it through the roadmap: **Planned**, **In progress**, **Shipped**. 3. When you mark it **Shipped**, its voters get an email and a changelog **draft** is created for it. 4. You edit the draft in the **Changelog** tab and publish it. Optionally, publishing also shows a banner in your product that links to the entry. Nothing reaches the changelog until you publish it. Announcements you publish in your product do not add changelog entries. ## Who can see and act Pick an access mode in **Roadmap & Changelog > Publish**: | Mode | Effect | | --- | --- | | Public | Anyone can read. Writing (vote, comment, submit) needs no sign-in. | | Identified | Anyone can read. Writing needs a visitor you identified. | | Private | Only customers you signed in with a verified identity can read. | Private boards need [identity verification](/guides/identity-verification) or a [sign-on link](/guides/board-sign-on). The server enforces the mode; hiding the page in your own app is not enough. ## Moderation New ideas and comments can wait for approval. Only approved content is public. Turn it on in **Publish** and review in **Roadmap & Changelog > Moderation**. ## Who voted Open an idea to see who voted and which account they belong to. Sort the idea list by identified people or accounts to build for your customers first. Visitors never see this. Public pages show no emails and no full names. ## Email When you change an idea's status or reply as the team, voters and commenters with an address get an email from your workspace name. Every email has a one-click unsubscribe link. ## Plans Hosted pages, embeds and custom domains are in every plan. --- # Steps that finish on an event A step can finish when something happens instead of when the visitor clicks a button. In the step's **Pages, targets and completion** section, pick **What completes this step**: | Choice | The step finishes when | | --- | --- | | The step's button | The visitor clicks it (the default). | | A click on the element | The visitor clicks the highlighted element (tooltip steps). | | An event | A matching event arrives. | ## Events Give the event name and, optionally, properties that must match (`plan=pro, source=import`). Choose where it may come from: - **From the browser or your server.** A `track()` call on the page finishes the step at once. An event your server sends does too. - **Only from your server (confirmed).** Use it for things the browser cannot prove, such as a successful payment or an import that finished in a job. A browser `track()` call never finishes this step. Send server events with your Secret key (see [Server events](/api/server-events)) and the person's `userId`, so the event reaches the same profile as the visitor. ## How the widget finds out For a server-confirmed step, the widget asks the server where the person is every 10 seconds while the step is open, and moves on when the server has moved them. There is no push channel for tours yet, so allow up to about 10 seconds after your server event. An event only moves a person who is on that step. A tour that is not started, or is on a different step, ignores it. --- # Surveys and NPS Ask visitors how it is going. Surveys support NPS, CSAT, CES and free-text feedback, and can use the block builder for custom layouts. ## Create a survey 1. Open **Surveys** in the dashboard. 2. Pick a type and write the question. 3. Choose where it appears: slide-out, modal or banner. 4. Choose when it appears: on page load, after scrolling, or when your code sends a specific event. 5. Set repeat frequency. 6. On the **Settings** tab, choose who sees it, then publish. Answers are on the **Results** tab. ## Trigger a survey from your code Set the survey trigger to **event** and enter an event name. Then call: ```ts import { track } from "@justonecx/sdk"; track("completed_onboarding"); ``` The next `track()` call with that exact name shows the survey once. ## Show once per order, ticket or purchase By default a person sees a survey once, or again after a throttle period. To ask after every order instead, set **Show once per (event property)** in the **Delivery** panel of the survey builder (event triggers only), for example `order_id`, and send that property with the event: ```ts track("purchase_completed", { order_id: "A-1042" }); ``` The survey now shows at most once for each different `order_id`, for each person. A second `track()` with the same order does nothing, whether the person answered or dismissed. Because every order is a new chance to ask, the Frequency setting and the throttle between surveys do not apply to a survey with this option. You can also send the event from your server with the Secret key, using `userId` and the same property. The survey then shows on that person's next page load, once for that order. ## Where a survey shows Surveys use the same targeting editor as tours and announcements, in the survey's **Settings** tab: who sees it (segments and conditions), which pages (show on, hide on, with exact, prefix, wildcard and regex rules) and when. A survey with page rules only opens when the visitor is on a matching page. An event trigger that fires on another page waits and shows when the person reaches a matching page. ## Follow-ups and branching You can show different follow-up questions by score band, for example a different prompt for detractors and promoters. ## Test mode Use the **Test survey** mode in the builder to see the survey without saving a response. ## Responses Responses appear in the dashboard under the survey. A survey type cannot change after its first response. ### Download responses Open the survey's **Results** tab and choose **Download responses (CSV)**. The file has one row per response with the answers, score, person and time. Cells that start with `=`, `+`, `-` or `@` are prefixed so spreadsheets do not run them as formulas. The same data is available from the API (admin sign-in required): `GET /workspaces/:id/surveys/:surveyId/responses?format=json` returns pages (`page`, `pageSize`); `format=csv` streams the whole file. --- # Targeting and segments Targeting decides who sees a tour, announcement or survey. The backend applies it before content reaches the browser, so hidden content is never sent. ## One model for tours, announcements and surveys Every tour, announcement and survey has the same three parts. Each part is optional, and they all have to match. | Part | What it does | Where it is checked | | --- | --- | --- | | Audience | **Only these segments** (a visitor in any of them), **Never these segments** (a visitor in any of them never sees it), optional inline conditions, and new vs returning visitors. | Server, before content is sent. | | Pages | **Only on these pages** and **Never on these pages**, each a list of rules. | The visitor's browser, on every page change. | | Schedule | A start and end time. Tours only: announcements set theirs in the **Schedule** section of their **Settings** tab, surveys have none. | Server. | Leaving a part empty means "no restriction": no segments and no rules show it to everyone, everywhere. ### Page rules Each rule has an operator and a value. A page is included when it matches any **include** rule (or when there are none) and matches no **exclude** rule. | Operator | Matches | | --- | --- | | is exactly | The path equals the value. | | starts with | The path starts with the value. | | contains | The path contains the value. | | matches pattern | `*` stands for one path segment, `**` for any depth: `/projects/*/settings`, `/docs/**`. | | matches regex | A regular expression on the path. An invalid expression never matches. | The query string and `#hash` are ignored unless you tick **query** or **#hash** on the rule. The builder has a **Test a URL** box that shows whether a URL would match. ### Turn the SDK off on some pages Use the [`excludePaths`](/api/init) option when nothing from JustOneCX should show on a page (an admin area, a preview frame): it hides chat, tours, announcements, surveys and What's new there. To turn off one kind everywhere on a page, use `disableTours`, `disableAnnouncements` or `disableSurveys`. A second copy of the SDK on the same page (a tag manager plus the npm package, for example) logs one warning and stays inactive, so chat and tours do not appear twice. ## Where the data comes from - [`identify`](/api/identify) sets user traits such as `plan` and `role`. - [`group`](/api/identify#group) sets account traits. - [`track`](/api/identify#track) records events. An anonymous visitor who never calls these still matches page rules, schedules and new-vs-returning rules. Segments and inline conditions need trait data. An account-level segment never matches a visitor who has not called `group()`. ## Create a segment 1. Open **Segments** in the dashboard. 2. Define conditions on the traits you send with `identify` and `group`. 3. Use the segment in a tour, announcement or survey. ## What a segment can use | Attribute | What it reads | | --- | --- | | Role, Plan | The `role` and `plan` traits you send with `identify`. | | Custom trait | Any trait you send with `identify` (enter its key). | | Account trait | A trait you send with `group` (enter its key). | | Identified | Whether the person has a user id (called `identify`) or is anonymous. | | Signup date, First seen, Last seen | When the person (or account) was first and last seen. | | Account MAU | Distinct active users of the account in the last 30 days. | | Performed event / Never performed event | Whether the person sent an event (from the browser or your [server](/api/server-events)), at least N times, optionally in the last N days. | | Completed tour / Dismissed tour | Whether the person finished or dismissed a tour (enter its key or id). | | Answered survey / Saw announcement | Whether the person answered a survey or saw an announcement (key or id). | | Opened chat, Chat rating | Whether the person started a chat, and whether they rated one at most N out of 5. | A segment that **measures accounts** can only use the account-level attributes (traits, signup/first/last seen, MAU). The rest describe one person. **What is not a segment attribute:** the page the visitor is on, their device, language and country. Those only exist in the browser, so they are checked there: use [page rules](#page-rules) for the current page and the SDK's context options for the rest. A segment is decided on the server before content is sent, so it cannot depend on them. ## Groups A segment is made of groups. Conditions inside a group combine with the group's **Match all** (every condition) or **Match any** (at least one). With two or more groups, the top-level choice decides how the groups combine: **all groups** or **any group**. This covers "(role is admin and plan is pro) or plan is free" without nesting further. Segments made before groups existed were converted when you upgraded: a chain of AND conditions became one group, and a chain with OR was split at each OR into groups joined by **any group**. The old chain was evaluated strictly left to right, which groups cannot copy exactly, so check a segment that mixed AND and OR. ## Operators Each condition compares one attribute with a value. Which operators you can pick depends on the attribute. | Operator | Meaning | | --- | --- | | equals / does not equal | Exact match (a date compares the day). | | contains / does not contain | Text contains the value, ignoring case. | | greater than / less than | Numbers, or dates for the signup date. | | between | From and to, both included. | | is set / is not set | The trait has a value / has none (an empty text counts as none). | | within last N days / not within last N days | The signup date is that recent / older. | **Negative operators match people who have no value.** "Plan does not equal pro" includes someone with no plan at all. Use **is not set** when you want to target people with a missing value on purpose, and **is set** to require one. "Account MAU less than 5" includes accounts and users with no activity, because they have an MAU of 0. ## Keep traits fresh Traits merge, so call `identify` and `group` on every page load. If you need targeted content to show right after a trait changes, `await identify(...)` and then call `init()` again. --- # Product tours A tour is a series of steps that point at elements on your page, or show a modal or banner. Visitors move through it with Next and Back. ## Create a tour 1. In the dashboard, open **Tours** and create one, from scratch or from a template. 2. On the **Builder** tab, add steps. For a tooltip step, pick the element it points at. 3. On the **Settings** tab, set targeting (who sees it, on which pages). The same tab holds the launcher, the A/B test, voice narration and version history. 4. Publish. The builder has three tabs: **Builder** (the steps), **Settings** (everything about the tour that is not one step) and **Results**. Save as template, Brand Kit, Unpublish and Delete are in the **⋯** menu next to Save. The SDK fetches published tours on `init()` and plays the ones that match the visitor. ## How steps are shown - A tooltip step highlights the element found by the step's selector. - The SDK scrolls the element to the middle of the screen before it places the tooltip. This also works inside scrollable panels and iframes, and it skips the animation when the visitor prefers reduced motion. - If the element is not on the page yet, the SDK waits for it (5 seconds by default; set up to 30 seconds per step). If it never appears, the step is skipped, the skip is recorded, and the tour finishes as **finished with skips** instead of a clean completion. The builder marks such steps "never saw it". - If no step in a tour can be shown, nothing is displayed and the tour is not marked as seen, because the visitor never saw it. - Finishing or dismissing a tour marks it as seen. It is not shown again automatically. See [Multi-page tours](/guides/multi-page-tours) for steps on different pages, text and role targets, event-completed steps and required steps. ## Replay and launcher Enable the **persistent launcher** in the **Launcher** section of the tour's **Settings** tab to show a "Replay tour" button. It stays available after the visitor finishes. You can set its screen corner. A visitor can dismiss it for good in their browser. You can also build your own button with [`startTour`](/api/reset#starttour). The tour's **frequency cap** limits only automatic playback. A manual replay always works. ## Checklists A checklist step shows tasks in a progress widget that stays in the corner of the page. Add one with **Add step → Checklist** on the Builder tab; a tour can be a checklist alone. A visitor completes a task by clicking it. You can instead bind a task to an event name. When your code calls `track("that_event")`, the task completes. Whichever happens first wins. ## Single-page apps Set `trackRouteChanges: true` so page-based targeting re-runs on each navigation. See [init](/api/init). ## Preview on your site The tour builder has a **Preview on your site** action. It uses the JustOneCX browser extension to play your draft on your own live page. --- # What's new widget An in-app panel that shows your changelog (or roadmap), with a badge for unread entries. It opens from your own button or from a floating button we add. Turn it on under **Roadmap & Changelog > Publish > On your website**, and pick how customers open it. **On your website** must be on too. Call [`init()`](/api/init) once first. ## Attribute, no code ```html What's new Roadmap ``` Works on any element, including ones your framework renders later. The SDK sets `data-justonecx-unread="3"` on the button when there are unread entries and adds a badge. Style it yourself with that attribute. ## Functions ```ts import { openChangelog, openRoadmap, getUnreadChangelogCount, onUnreadChangelogCountChange } from "@justonecx/sdk"; openChangelog(); const unread = getUnreadChangelogCount(); const stop = onUnreadChangelogCountChange((count) => setBadge(count)); ``` From the script tag use `window.JustOneCX.openChangelog()` and the other functions. ## Unread An entry is unread when it was published after the visitor last opened the panel. Identified visitors keep that state across devices. --- # Frameworks Every framework uses the same calls. Three rules apply everywhere: 1. Call `init()` once, in the browser only, after the app mounts. 2. In single-page apps, pass `trackRouteChanges: true`. The SDK then re-runs itself on each client-side navigation, so page targeting stays correct. 3. Call `identify()` after sign-in and `reset()` on sign-out. Use these options in all examples: ```ts const options = { publicKey: "pk_your_workspace_key", apiUrl: "https://api.justonecx.com", trackRouteChanges: true, }; ``` ::: info The examples import `@justonecx/sdk`. If you have not installed it, use the [script tag](/install/script-tag) instead. ::: ## React, Next.js, Remix, Preact ```tsx "use client"; // Next.js App Router only import { useEffect } from "react"; import { identify, init } from "@justonecx/sdk"; export function JustOneCX({ user }: { user?: { id: string; plan: string } }) { useEffect(() => void init(options), []); useEffect(() => { if (user) void identify(user.id, { plan: user.plan }); }, [user]); return null; } ``` Render `` once in your root layout. ## Vue and Nuxt ```ts // Vue: main.ts, after app.mount() import { init } from "@justonecx/sdk"; void init(options); ``` ```ts // Nuxt: plugins/justonecx.client.ts // The ".client" suffix keeps it out of server rendering. import { init } from "@justonecx/sdk"; export default defineNuxtPlugin(() => { void init(options); }); ``` ## Angular ```ts import { isPlatformBrowser } from "@angular/common"; import { Component, PLATFORM_ID, inject } from "@angular/core"; import { init } from "@justonecx/sdk"; @Component({ selector: "app-root", templateUrl: "./app.html" }) export class App { constructor() { if (isPlatformBrowser(inject(PLATFORM_ID))) void init(options); } } ``` ## Svelte and SvelteKit ```svelte ``` Put this in `+layout.svelte` (SvelteKit) or `App.svelte`. ## Solid and SolidStart ```tsx import { onMount } from "solid-js"; import { init } from "@justonecx/sdk"; onMount(() => void init(options)); ``` ## Astro, Lit, Alpine, jQuery, plain TypeScript Call `init(options)` from any client-side script. In Astro, put it in a ` ``` Place it before ``. The script reads its own `data-*` attributes and starts by itself. ## Attributes | Attribute | Required | Description | | --- | --- | --- | | `data-public-key` | Yes | Your workspace public key. | | `data-api-url` | Yes on real sites | Backend origin. Without it the SDK uses `http://localhost:8000`, which only works for local development. | | `data-track-route-changes` | No | Set to `"true"` on sites that change pages without a full reload. | ## Pin a version (optional) The URL above always serves the latest SDK and is cached for five minutes. We recommend it for almost every site. Pin a version only if you need to lock to one release. A pinned file never changes. Replace `` with the version you want: ```html ``` See [SDK versions](/versions). ## Calling the API The script adds `window.JustOneCX`: ```js window.JustOneCX.identify("user-42", { plan: "growth" }); window.JustOneCX.track("clicked_upgrade"); window.JustOneCX.reset(); ``` Board functions are there too: `mountRoadmap`, `mountIdeas`, `mountChangelog`, `openChangelog`, `openRoadmap`. The script also registers ``, `` and ``. When a board first appears the script loads `justonecx-boards.global.js` from the same place. See [Embed](/guides/embed-roadmap-changelog). Calls made before the script has loaded fail. Place your own code after the script tag, or run it after the `load` event. ## Content Security Policy If your site sends a CSP header, allow our script and API origins. See [Content Security Policy](/security#content-security-policy). ## Platform notes Step-by-step paths for each builder are on [Website builders](/install/website-builders). In short: - **WordPress**: add the snippet with a header/footer plugin, or in your theme's `footer.php` before `wp_footer()`. - **Webflow**: Project settings → Custom code → Footer code. - **Shopify**: edit `theme.liquid` and paste the snippet before ``. - **Google Tag Manager**: use a Custom HTML tag that fires on all pages. Add `data-track-route-changes="true"` if the site is a single-page app. --- # Website builders You don't need a developer to add JustOneCX to a site made with a website builder. Every builder below has a place to paste one snippet. You paste it once, publish, and everything you build in the dashboard shows up on the site. ## Before you start 1. In the dashboard, open **Developers** and copy your snippet. It looks like this and already holds your Public key: ```html ``` 2. Add your live site address under **Settings → Developers → Domains & CORS**, for example `https://www.example.com`. Without it, nothing shows. See [Allowed origins](/guides/allowed-origins). 3. After you paste the snippet, **publish your site**. Most builders don't run custom code in their editor preview. The paths below are the ones each builder documents today. Builders move menus around, so if a name differs, search that builder's help for "custom code". ## Webflow 1. Open **Site settings → Custom code**. 2. Paste the snippet into **Footer code**. 3. Save, then publish. Webflow documents custom code as a paid-plan feature, so check your plan if the field is missing. Code that only some pages need goes in that page's own settings instead. ## Framer 1. Open your site's settings and find **Custom Code**. 2. Paste the snippet into the **End of `` tag** field. 3. Publish. The change doesn't show in the editor preview. ## Shopify 1. Open **Online Store → Themes**, then **Actions → Edit code**. 2. Open `theme.liquid` under **Layout**. 3. Paste the snippet just above the closing `` tag. Don't remove the lines around it. 4. Save. If your theme has more than one layout file, paste it into the one your store pages use. ## Wix 1. Open **Settings → Custom Code** in your site's dashboard (in the **Advanced** section). 2. Choose **Add Custom Code** and paste the snippet. 3. Under **Place Code in**, choose **Body - end**, and apply it to all pages. 4. Apply, then publish. Wix asks for a published site with a connected domain. Wix doesn't support third-party code, so test on your live site. If nothing appears, check the [troubleshooting page](/troubleshooting). ## Squarespace 1. Open **Settings → Advanced → Code Injection**. 2. Paste the snippet into the **Footer** box. 3. Save. Code Injection needs a Business plan or higher. It doesn't run on checkout pages. ## WordPress Use a plugin that adds code to your site's footer, then paste the snippet into its footer box. If you edit your theme instead, add the snippet in `footer.php` just before `wp_footer()` and use a child theme, so a theme update doesn't remove it. ## Google Tag Manager Create a **Custom HTML** tag with the snippet and fire it on **All Pages**. ## Check that it works Open your published site in a new tab, then look at the status next to the page title in the dashboard. It changes from **Waiting for first visit** to **Connected**. The **Event log** shows the visit as it arrives. If it doesn't, see [Troubleshooting](/troubleshooting). ## What a builder can't do for you A website builder can't tell JustOneCX who is signed in. Everyone who visits sees the same tours, announcements and surveys, and the tour or survey can still target a page or a time. To show something only to paying users or to new sign-ups you need your developer to add [`identify`](/api/identify), or an AI assistant in your own project. See [Build with AI](/ai/). ## Built with an AI app builder If an AI tool such as Lovable made your app, ask it: "Add this script tag to my app's `index.html` before ``" and paste the snippet. Then publish. For the steps for connecting an AI assistant to JustOneCX itself, see [MCP server](/ai/mcp#lovable-and-other-chat-based-builders). --- # Public developer docs VitePress site served at `https://docs.justonecx.com`. Audience: developers adding the SDK to their product. This is **not** the internal `docs/` site (QA, architecture, database) and nothing internal belongs here. ```sh pnpm --filter public-docs dev # http://localhost:8082 pnpm --filter public-docs build # vitepress build + scripts/postbuild.mjs pnpm --filter public-docs test # checks code samples against the SDK's real exports ``` ## What the build emits `scripts/postbuild.mjs` adds AI-friendly files to `.vitepress/dist` next to the HTML: - `/llms.txt`: index of every page. - `/llms-full.txt`: every page in one file. `packages/mcp` reads this file for `search_docs`. - `/.md`: raw Markdown per page. - `/ai/justonecx-integration/SKILL.md`: agent skill, copied from `public/ai/`. ## Writing rules - Write for someone who has never seen the product. Short pages, one task each, copy-paste code. - Use the placeholder key `pk_your_workspace_key` and the real URLs `https://api.justonecx.com` and `https://app.justonecx.com/sdk/justonecx-sdk.global.js`. - `pnpm test` fails if a sample imports a name `@justonecx/sdk` does not export, or calls `window.JustOneCX.` for a function the script-tag bundle does not expose. Keep samples real. - New page: add the file, add it to the sidebar in `.vitepress/config.ts`. - Never hardcode an SDK version number in a page. Pinned URLs use ``, and the only version-bearing text is the "Current version" section of `versions.md`. Each SDK release adds its entry there (see `packages/sdk/DEVELOPMENT.md`, "Releasing"). - `@justonecx/sdk` is on npm (first published 2026-10-03; see `npm view @justonecx/sdk version` for the current one). The hosted MCP server at `/mcp` is the one way to connect an AI assistant; `@justonecx/mcp` is not published. The backend with `/mcp` is deployed, so `ai/mcp.md` has no "Coming soon" warning; the connect snippets there are mirrored in `MCP_CLIENTS` (`apps/frontend/src/components/landing/landingContent.ts`), so change both together. ## Deploy `scripts/vps/deploy.sh` builds this app and rsyncs it to `/var/www/justonecx-docs`. Use `deploy.sh --docs-only` for a docs-only release. Caddy config lives in `scripts/vps/Caddyfile`. --- # Security ## The public key is public The key that starts with `pk_` is like a publishable key. It is safe in page source. It identifies your workspace and only grants access to content you have published. It does not need to change when you add or edit content. Rotate it from **Settings → Developers** only if you want to retire an embed. ## Protect identities Anyone with your public key can call `identify` with any user id. Turn on [identity verification](/guides/identity-verification) and sign user ids on your server. Never put the Secret key in client code. ## Allowed origins The [allow-list](/guides/allowed-origins) restricts which browsers can use your key. It is not authentication. ## Content Security Policy If your site sends a Content-Security-Policy header, allow: | Directive | Value | | --- | --- | | `script-src` | `https://app.justonecx.com` (script tag install only) | | `connect-src` | `https://api.justonecx.com` and `wss://api.justonecx.com` (chat) | | `script-src` (boards) | The same origin also serves `justonecx-boards.global.js`, loaded the first time a board appears. Set `boardsUrl` in `init()` to move it. | | `style-src` | `'unsafe-inline'`, because the SDK injects one `