Journeys

Journeys are the foundation of the Odyssey platform. A journey represents a multi-step process or workflow that users navigate through, such as a grant application, permit request, or onboarding flow. Odyssey tracks user behavior throughout these journeys to help you identify friction points and optimize completion rates.

What is a journey?

A journey is a defined sequence of steps that users move through to complete a task. Each journey has:

• A unique identifier (slug) within your organization
• A display name for human readability
• A collection of steps arranged in order
• Configuration for tracking and analytics
• Optional allowed origins for CORS security

Think of a journey as the blueprint for a form or workflow. Once defined, you can embed tracking into your actual application to collect behavioral data.

Journey lifecycle

1. Create the journey

First, create a journey by defining its basic properties and structure:

curl -X POST https://odysseylabs.ai/api/journeys/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "small-business-grant",
    "displayName": "Small Business Grant Application",
    "sourceSystem": "custom",
    "allowedOrigins": ["https://grants.example.com"]
  }'

2. Define steps

Add steps to your journey to represent each page or section:

curl -X POST https://odysseylabs.ai/api/journeys/small-business-grant/steps \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "stepKey": "eligibility-check",
    "name": "Eligibility Verification",
    "stepType": "eligibility",
    "index": 0,
    "fieldCount": 5
  }'

3. Integrate the embed script

Add the Odyssey embed script to your application to start collecting analytics:

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

The embed script automatically tracks user behavior without blocking your page or collecting PII.

4. Monitor and optimize

Once data starts flowing, you can:

• View completion rates and drop-off points
• Analyze mobile vs desktop behavior
• Identify steps with high abandonment
• Track median time to completion

Journey configuration

Source systems

Journeys can originate from different sources:

• custom - Journeys you build yourself
• simpliGov - Imported from SimpliGov platform
• unknown - Legacy or unspecified source

Environments

Separate production and staging data:

• production - Live user data
• staging - Testing and development

Allowed origins

For security, you can restrict which domains can send events to your journey:

{
  "allowedOrigins": ["https://app.example.com", "https://staging.example.com"]
}

Events from other origins will be rejected. Leave empty to allow any origin (not recommended for production).

Step configuration

Steps are the individual pages or sections within a journey. Each step has:

Step identification

• stepKey - Case-sensitive, stable identifier used by the embed script (e.g., "eligibility", "upload-docs"). Must match the form field id attribute exactly or it will not be tracked.
• name - Human-readable name for dashboards (can be chosen freely)
• index - Position in the journey sequence (0-based)

Step types

Classify steps by their purpose:

• eligibility - Qualification or screening questions
• upload - Document or file upload pages
• review - Summary or confirmation pages
• submit - Final submission pages
• information - Informational or instructional pages
• input - Data entry forms
• selection - Choice or option selection
• payment - Payment processing
• signature - Electronic signature pages
• other - Miscellaneous step types

Field types

For form steps, specify the primary field type:

• text_box, text_area - Text input fields
• radio_button, check_box, drop_down - Selection fields
• file_upload, multi_upload - File handling
• datepicker - Date selection
• signature_field - Signature capture
• And many more...

Complexity metrics (optional)

Track step complexity to understand user burden:

• readingLevel - Grade level required to understand the content
• fieldCount - Number of input fields on the step
• requiredArtifacts - Number of documents needed

Event tracking

The embed script automatically collects these events:

Session events

• session_start - User begins a new session
• session_end - Session completes or times out

Navigation events

• page_view - User views any page
• step_view - User enters a specific step

Interaction events

• field_focus - User focuses on an input field
• field_blur - User leaves an input field
• field_change - User modifies field content

Validation events

• validation_error - Form validation fails

Submission events

• submit_attempt - User tries to submit
• submit_success - Submission succeeds

Analytics events

• dropoff_signal - User shows abandonment behavior

Journey analytics

Once data is flowing, Odyssey provides rich analytics:

Health metrics

• Has steps configured
• Has recent events (last 24 hours)
• Session count
• Has simulation snapshots

Behavior metrics

• Completion rate - Percentage of sessions that finish
• Mobile rate - Percentage on mobile devices
• Median time to complete - Typical duration
• Top drop-off step - Where most users abandon

Event counts

Real-time counts by event type for the last 24 hours.

Unmapped steps

Steps that were configured but haven't received any events in the last 7 days (potential tracking issues).

Best practices

What's next?