Widget Installation

The Tracya widget is a small JavaScript snippet you add to your web app. Once installed it fetches your published flows from the API and displays them automatically.

Prerequisites

A Tracya account with at least one project.
Access to your app's HTML, ideally the ability to add a script tag before </body>.
Your app must be reachable from a browser (localhost works during development).

Step 1 — Get your project ID

Sign in at https://app.tracya.io.
Open the Projects tab in the top navigation bar.
Each project row shows its ID in monospace. Click Copy next to the project you want to instrument.

The ID is a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. This is the value you pass as projectId in the snippet.

Step 2 — Add the snippet

Paste the following before the closing </body> tag of every page where you want Tracya flows to appear.

<script>
  window.OnboardFlow = window.OnboardFlow || { q: [] };
  window.OnboardFlow.q.push(['init', {
    projectId: 'YOUR_PROJECT_ID',
    apiUrl: 'https://api.tracya.io'
  }]);
  (function () {
    var s = document.createElement('script');
    s.src = 'https://api.tracya.io/static/widget/onboardflow.min.js';
    s.async = true;
    document.head.appendChild(s);
  })();
</script>

Replace YOUR_PROJECT_ID with the UUID you copied in Step 1.

The snippet uses an async queue pattern: commands pushed to OnboardFlow.q before the script loads are replayed automatically once the widget initialises.

URL parameter fallback (testing only)

You can skip the snippet entirely by appending query parameters to any page URL:

https://your-app.com/page?of_project=YOUR_PROJECT_ID&of_api=https://api.tracya.io

The widget auto-detects of_project and calls init() with the values from the URL. Do not use this in production.

Step 3 — Verify installation

Open your app in a browser, then open the browser console (F12 → Console).

A successful boot produces no output. If something goes wrong, the widget logs a prefixed error:

Console message	Cause
`[OnboardFlow] Missing projectId in config.`	`projectId` was not passed to `init()`.
`[OnboardFlow] init() already called — ignored.`	`init()` was called twice on the same page. Remove the duplicate call.
`[OnboardFlow] Error loading flows: …`	Network error, CORS rejection, or invalid project ID. See Troubleshooting below.

To confirm the widget fetched your flows, check the Network tab and look for a request to /v1/flows?projectId=…. A 200 response with a JSON array means everything is working.

Configuration options

OnboardFlow.init() accepts a single configuration object.

Key	Type	Required	Description
`projectId`	`string`	Yes	UUID of the project, copied from the Projects tab.
`apiUrl`	`string`	No	Base URL of the Tracya API. Defaults to `'mock'` (returns empty flows). Set to `'https://api.tracya.io'` in production.
`onComplete`	`function`	No	Callback invoked when a user completes a flow. Receives no arguments.

Public methods

Once init() has been called, the following methods are available on window.OnboardFlow:

Method	Description
`startFlow(flowId)`	Manually trigger a flow with trigger type `manual`. `flowId` is the UUID returned by the API.
`reset()`	Clears all stored user progress in `localStorage`. Useful during development to replay flows.

SRI integrity hashes

Subresource Integrity (SRI) hashes are generated after each widget build and recorded in widget/SRI.md in the repository. The hash for the current build is:

<script
  src="https://api.tracya.io/static/widget/onboardflow.min.js"
  integrity="sha384-hbOo5ZpoMoZM6uuFOyd37pTpudXBcO2+oyGYN090LHZzM/8tichUTluSpi4/70oN"
  crossorigin="anonymous"
  defer>
</script>

Note: This hash is valid for the current build. It will change after each widget deployment. Always verify against widget/SRI.md in the repository.

To generate the hash yourself after a local build:

cat widget/dist/onboardflow.min.js | openssl dgst -sha384 -binary | openssl base64 -A

Note: the async queue pattern shown in Step 2 dynamically creates a <script> element, which does not support the integrity attribute. Switch to a static <script> tag as shown above if you want SRI enforcement.

Troubleshooting

CORS error in the browser console

The API rejects requests from origins not listed in CORS_ORIGINS. If you see a CORS error:

Check the CORS_ORIGINS environment variable on the API server — it must include your app's exact origin (scheme + hostname + port), comma-separated.
Restart the API after updating .env.

Content Security Policy (CSP) blocking the script

If your app sets a Content-Security-Policy header or meta tag, ensure it allows:

script-src: the widget origin (https://api.tracya.io)
connect-src: the API origin (https://api.tracya.io)
style-src 'unsafe-inline': the widget injects inline styles for tooltips and overlays

Element not found / steps not anchoring

Steps are anchored to CSS selectors captured in the editor. If a selector no longer matches:

The step is silently skipped.
Open the browser console and look for [OnboardFlow] warnings.
Re-open the flow in the editor, delete the step, and re-select the element.

Flows not appearing after installation

Confirm the project ID in the snippet matches the project shown in the dashboard.
Confirm apiUrl points to https://api.tracya.io (not 'mock').
Check that at least one flow is published and active (visible in the Editor tab).
Verify the page URL origin is allowed in CORS_ORIGINS.