Installation

To get started with Odyssey, you'll need to install the Odyssey embed script. The embed script is a lightweight JavaScript file that collects events and sends them to the ingest API. It automatically tracks user behavior without blocking your page or collecting PII.

Creating a Journey

Before installing the embed script, you'll need to create a journey. A journey is a multi-step process or workflow that users navigate through, such as a grant application, permit request, or onboarding flow. You can create a journey using the API or the dashboard.

Refer to the Journeys API for more information on creating a journey.

Learn more about journeys

Script Installation

To install the Odyssey embed script, you'll need to add the script tag to your journey pages:

Name
data-org
Type
string
Description
Your organization slug.
Name
data-journey
Type
string
Description
The journey slug this page belongs to.
Name
data-endpoint
Type
string
Description
The ingest API endpoint URL. For production, use https://odysseylabs.ai/api/ingest. For enterprise customers using their own infrastructure, use the endpoint provided in your organization dashboard.
Name
data-env
Type
string
Description
Environment: prod, staging, or dev. Defaults to prod.

Example embed script

HTML

Embed script

<script
  src="https://odysseylabs.ai/embed/embed-v1.global.js"
  data-org="your_org_slug"
  data-journey="your_journey_slug"
  data-endpoint="https://odysseylabs.ai/api/ingest"
  data-env="prod"
  async
></script>

You can find the exact embed script to use for your journey in the journey configuration. Head to the Instrumentation tab to copy the script snippet with the data attributes correctly set.

Content Security Policy (CSP)

If you are using a Content Security Policy (CSP) on your website, you will need to add the Odyssey embed script to the allowed sources.

Content Security Policy (CSP)

Content-Security-Policy: script-src 'self' https://odysseylabs.ai;

Alternatively, you can pass a cryptographically secure random nonce to the script tag to allow the script to be executed.

Embed script with nonce

<script
  src="https://odysseylabs.ai/embed/embed-v1.global.js"
  data-org="your_org_slug"
  data-journey="your_journey_slug"
  data-endpoint="https://odysseylabs.ai/api/ingest"
  data-env="prod"
  nonce="..." // cryptographically secure random nonce, e.g. from `crypto.randomUUID()`
  async
></script>

Debugging

You can enable debug mode to see the events being collected in the browser console. This is useful for ensuring the embed script is working correctly. The debug mode also allows you to see the events being collected in real-time. This is useful for ensuring your step keys match the steps you have defined in the journey.

Step keys are derived from the form field id attribute. These must match the step keys exactly. For example, if you have a step with the key eligibility, the form field must have the id attribute eligibility. If steps are not configured correctly, the embed script will not collect event data.

It is highly recommended to enable debug mode during development and testing to verify the step keys are correct, or use one of our automated step extraction tools in the dashboard to import your steps. Once you are satisfied with the configuration, you can disable debug mode.