​

Browser, React, embedded, and hosted

​

Embedded journey

import {
  createParticipantClient,
  createParticipantSessionController,
  MemoryParticipantQueueStorage,
} from "@apart-ai/synapse/participant";
import { mountEmbeddedParticipant } from "@apart-ai/synapse/participant/embedded";

const client = createParticipantClient({
  baseUrl: SYNAPSE_API_URL,
  participantToken,
});
const controller = createParticipantSessionController({
  client,
  queueKey: `evaluation:${opaqueEvaluationRef}`,
  storage: new MemoryParticipantQueueStorage(),
  consent: {
    beforeStart: async (session) => showConsent(session.consent.notice_text),
  },
  onComplete: (report) => renderResult(report),
});

const mounted = mountEmbeddedParticipant(
  document.querySelector("#synapse")!,
  { controller },
);

mounted.destroy();
controller.dispose();

​

Question pages

import {
  createParticipantSessionController,
  ParticipantPageRejectedError,
} from "@apart-ai/synapse/participant";

const controller = createParticipantSessionController({
  client,
  queueKey: `evaluation:${opaqueEvaluationRef}`,
  pageSize: 5,
  consent: {
    // Or call controller.setConsent(true) from your own consent screen.
    beforeStart: async (session) => showConsent(session.consent.notice_text),
  },
});

// Once consent is accepted, start() and resume() load the page:
// render controller.getSnapshot().page.questions.
try {
  await controller.submitPage([
    { questionId: "goal", state: "answered", answer: { option_id: "growth" } },
    { questionId: "horizon", state: "skipped" }, // "I don't know"
    { questionId: "income", state: "declined" }, // "Prefer not to answer"
  ]);
} catch (error) {
  if (error instanceof ParticipantPageRejectedError) showPageRefreshedNotice();
}

• snapshot.page holds the current page. It stays null until consent is accepted. snapshot.next mirrors its first question, so code that checks snapshot.next.complete keeps working.
• submitPage sends the page’s responses in page order, usually in one request with the page’s question_viewed events, then loads the next page. batchSize (events per request, default 20) still applies: a page queues up to twice pageSize events, so a smaller batchSize, or older events queued ahead of the page, can split it across requests.
• snapshot.submittedPage is the page’s batch_id from the moment its responses are queued until the next page loads or Synapse rejects the page. Show the page read-only while submittedPage === page.batch_id. It is part of the controller state, so it survives UI remounts.
• Submitting the same page again with the same answers only retries delivery. Different answers reject with an Error and nothing is queued.
• Offline responses stay queued, and the controller loads the next page once the queue is delivered.
• If the answers were delivered but the next page failed to load, submitPage still resolves with the same page. snapshot.error says why, and the controller retries the load; a “Try again” button can call loadNextPage().
• If Synapse rejects page events (409, 422, or nothing accepted), the controller drops every page event from the queue, reloads the current page, sets snapshot.error to a ParticipantPageRejectedError, and calls onError. This also happens during background delivery and for a queue restored after a reload, so show the “page was refreshed” notice whenever snapshot.error is a ParticipantPageRejectedError. submitPage rejects with it when its own delivery was rejected.
• 401, 403, 404, or 410 mean the link no longer works. The queue is kept, the page is not reloaded, snapshot.status becomes "error", and submitPage rejects with the original ApiError.
• Pages served by this server version never hold a question that another page question’s response could hide or show, so raw API clients can post a page’s responses in any order.
• The embedded renderer always shows one question at a time.

​

Hosted journey

import { mountHostedParticipant } from "@apart-ai/synapse/participant/hosted";

const hosted = mountHostedParticipant(container, {
  hostedUrl: session.hosted_url!,
  baseUrl: PUBLIC_SYNAPSE_WEB_ORIGIN,
  onComplete: (evaluationId) => showCompletion(evaluationId),
  onReport: (report) => renderReport(report),
});

hosted.destroy();

​

Consent and queue safety

• The controller sends the server-pinned consent_accepted event before any restored or new participant traffic.
• mountEmbeddedParticipant starts the controller. Do not call start() a second time after mounting.
• Use MemoryParticipantQueueStorage by default. Local storage can retain assessment content in clear text and needs an explicit privacy review.
• Use an opaque evaluation reference as the queue key—never the participant token, an external ID, or a report token.
• skip records unknown; decline records an explicit refusal. Neither is imputed as a negative answer.
• Call dispose() and destroy the renderer when the host view unmounts.