Before someone joins
The SDK asks whether an approved interview invitation is available. The base request fields are shown below. This release also sends funnel: "v1", an optional previous signed offer, and a DNT/GPC opt-out flag; automatic mode and signed-in identity add the fields described below:
{
"operation": "offer",
"key": "your public workspace UUID",
"device": "a random browser-session identifier"
}| Data | Use and handling |
|---|---|
| Workspace key | Selects your workspace. Public configuration, not an account password. The server checks the website origin against that workspace. |
| Session identifier | Random 256-bit value stored in sessionStorage under justusability-widget-device:WORKSPACE_KEY. Links an invitation to that browser session. It is not a fingerprint. Browser session restore or a copied tab can extend its lifetime. If storage is blocked, it stays in memory. |
| Signed-in state | identify(userId) enables signed-in eligibility. In this release the ID is transmitted, over TLS, to your own workspace’s Justusability endpoint and only on the offer request, so that a cohort-targeted research card can tell whether you are in the cohort its question is about. It is hashed workspace-scoped on arrival and never stored raw in any table, log or payload. The SDK holds it in memory for the page’s lifetime and never writes it to storage, a cookie, a URL, a fragment or a log. This is a client-side display signal, not proof of a participant’s identity. |
| Network information | Hosting infrastructure receives ordinary request metadata, including IP address, time and browser headers. The website’s Origin is required. SDK offer requests omit cookies and suppress Referer. The generated script tag uses anonymous cross-origin loading and a no-referrer policy; same-origin script loads may still include that origin’s cookies. This is not a claim of complete anonymity. |
| Page contents and activity | The research runtime does not collect host-page text, fields, URLs, browsing history or credentials. In this release it reports its own invitation display, first interaction, open, dismiss and minimize states. Tracking requests contain only a signed offer, session device token, allowlisted event and surface; no supplied user ID. The backend sends opaque invitation/workspace IDs and bounded metadata to PostHog in the US, without participant profiles or raw capability/device tokens. DNT/GPC disables optional reporting without preventing participation. Like other page scripts it technically runs with page privileges; these are inspectable implementation limits, not a browser sandbox guarantee. |
| Server contact receipt | A valid request updates the workspace’s last installation-contact time. An available offer binds a hash of the session identifier to a signed, expiring invitation. Connection alone does not prove an interview occurred. |
The SDK writes no cookies or localStorage. The participant page has separate microphone preferences and consented research records described in the participant privacy notice.
A display requires at least half the launcher in a visible viewport for one second, or a direct interaction. It does not prove attention. A random invitation ID connects controls with server-confirmed interview admission, connection and completion; it survives polling for at most 24 hours. Missing later events mean no later activity observed within that window. Blocked or lost telemetry can undercount. Booking-page clicks do not prove a booking. Existing pinned installations require an explicit upgrade.
After someone chooses to participate
Clicking the launcher opens Justusability’s interview experience in an isolated panel on the product page. Each new interview is human-led. AI interviewing, takeover and backup are deferred, so researcher unavailability does not create a replacement interview. Minimize preserves the same session; it does not mute, stop or withdraw an interview. The participant reviews eligibility, the thank-you offer and research/recording consent before starting. Recording, transcription and analysis are separate server features; they are not hidden inside the invitation SDK.
- Collected during an interview: consent and eligibility receipts, interview audio when agreed, transcript, operational call records and derived findings.
- Access: research belongs to the client workspace. Its authorized members and the service processes needed to deliver the interview have access under the product’s access controls.
- Retention and withdrawal: the approved interview specifies its retention period, as displayed in the invitation. Withdrawal or expiry triggers removal of audio, transcripts and derived findings. Removing the SDK only stops future recruitment; it does not delete interview records, account records or provider logs.
- Providers: hosting/storage use Vercel and Supabase; the voice path uses LiveKit, with Twilio for configured phone handoff; transcription/analysis use OpenAI. The exact path depends on the enabled features. See the privacy notice for wider product providers and contact us for a deployment-specific processing inventory.
- AI use: interview material is processed to transcribe and analyse the research. The privacy notice states that workspace content and research responses are not used to train models.
The browser SDK source cannot establish hosting regions, provider log retention or backup deletion times. A verified deployment-specific statement covering those details and the full provider inventory is still being prepared. If your organization requires it for installation approval, contact Justusability contact before proceeding.
Inspect the exact release
Version numbers identify a release; hashes identify its bytes. The script URL includes both, and an integrity attribute lets the browser reject a modified bundle. The manifest and source snapshot are available beside the bundle.
Review this build, its integrity hash and source snapshot →
Try the SDK and inspect its requests
The demo runs this built SDK against simulated offer responses. It displays request fields and lifecycle state, creates no interview and requests no microphone. It does not certify production infrastructure or replace an independent review.
npm installation
npm install --save-exact @justusability/sdk@0.1.0Commit your lockfile and review upgrades. The release workflow verifies the tag against the package version. The initial release is published through an authenticated maintainer session and does not claim npm provenance. Trusted publishing must be configured before future automated releases. Check the registry receipt before claiming provenance. Provenance links source and build history; it does not certify that code is secure. How to check npm provenance.
Script installation and self-hosting
Go live supplies your workspace key, exact script URL, SHA-384 integrity, anonymous cross-origin loading and no-referrer policy. Keep them together. Avoid the mutable /sdk.global.js alias when you need controlled upgrades.
You can download and serve the reviewed bundle yourself. Keep its hash unchanged and explicitly set data-justusability-endpoint to your Justusability workspace host; otherwise script auto-init uses the bundle’s host. Self-hosting the bundle does not self-host the interview service.
Verify the downloaded bundle yourself
openssl dgst -sha384 -binary sdk.global.js | openssl base64 -ACompare the result with the manifest’s integrity value after its sha384- prefix. Review the source snapshot as well: a hash supplied beside a file establishes consistency, not independent trust in the publisher.
Automatic mode adds installation: "automatic-v1" to offer requests. The service records separate last-contact timestamps for signed-out and identified contexts. These are integration signals, not verified identity or proof that every page has the widget.
You control where it runs
- Audience: new integrations use
automatic: the server applies the active question’s approved audience. Supply a real user ID when signed in, null when signed out, or undefined while authentication loads. Legacyall_visitorsandsigned_inmodes remain supported. There is no implicit default. - Pause:
Justusability.pause()removes the invitation and stops offer requests.resume()resumes for the selected audience. - Remove: call
destroy()to stop recruitment timers and listeners, then remove the loader/component and package. An already opened interview panel remains reachable until you leave the page. You may remove the specific sessionStorage key above if you also want to clear the SDK’s local session identifier. - Rollback: retain the previously reviewed bundle and matching hash or restore the previous lockfile. Test compatibility with the current interview service; do not roll back to the retired 0.3.x capture API.
Offer polling runs every 15 seconds while the page is visible and the selected audience is eligible, plus initialization and explicit lifecycle changes. One current request is in flight, with a ten-second timeout. Pausing, identity changes, hiding the tab and destruction invalidate late responses. Failures remove the invitation and are handled without throwing into normal host-page interaction.
Bundle and gzip sizes on the release page are measured build artifacts, not a promise about page speed. Test your app’s responsiveness, layout, network use, slow loads, blocked storage and logout on your supported browsers. The SDK uses inline launcher styling; validate it against your CSP. Preserve your CSP and nonce rules—do not disable them to make installation pass.
Security questions and review status
No independent security audit is claimed for research SDK 0.1.0. Automated checks cover request fields, identity exclusion, stale responses, cleanup and artifact integrity. Their scope is narrower than a security assessment of the SDK and interview backend together.
Report a suspected vulnerability privately to Justusability contact. Include the version, affected feature and a minimal reproduction without customer data. Data-access and deletion questions go to Justusability contact.