Event Data Schema

Welcome to the Userpilot Event Data Schema documentation! This guide provides a comprehensive overview of the structure, attributes, and relationships of events exported from Userpilot. It is designed to help data analysts, engineers, and business users understand and utilize Userpilot event data for integration, analytics, and reporting purposes.

Below, you'll find detailed explanations of each event field, example payloads, and best practices for working with Userpilot data in your own systems.

Event Structure

Event Name & Type

The event_name field tracks the name of the event and varies depending on the event_type :

• For identify_user , identify_company , and page_view events: This field will be empty.
• For track events: The value will represent the name of the event being passed programmatically or through the button-tracking feature.
• For track_feature events: The value will contain the id of the tracked feature tag.
• For interaction events:
  • The format is {entity_type}:{entity_id}:{entity_interaction_status}
  • Example: checklist:2:SEEN , experience:448:DISMISSED , resource_center:1:ENGAGED .

Source

The source field indicates where the event was captured. The default value is web-client , but it can vary depending on the source of the event:

• web-client: Captured through the web SDK.
• backend-http: Captured via HTTP endpoints.
• backend-hubspot: Captured through the HubSpot integration.
• backend-salesforce: Captured through the Salesforce integration.
• backend-segment: Captured through SegmentIO integration.

Attributes Schema

The attributes field varies depending on the event type:

• For identify_user , identify_company , and track events: This field will contain custom attributes passed during the event tracking.
• For page_view and track_feature events: This field will be an empty object.
• For interaction events: Attributes vary based on the engagement entity type and provide specific interaction details (e.g., checklist:2:SEEN , experience:448:DISMISSED ). (see next section for details)
  • Experience refers to flow

Interaction Attributes

For interaction events, the attributes vary based on the specific engagement entity and the event type. Below are common interaction events and the relevant attributes associated with each.

Surveys (survey_module events)

These events track user interactions with survey modules, including responses, dismissals, and submissions.

Example:

{
  "event_name": "survey_module:49:COMPLETED",
  "attributes": {
    "feedback": "318b72c9-b1ad-4bf6-854b-26d32ac9d281",
    "interaction_id": "survey_module_49",
    "is_dismissed": "0",
    "parent_id": "survey_13",
    "status": "COMPLETED",
    "survey_question": "",
    "variant": "multiple_choice"
  }
}

Checklists (checklist and checklist_task events)

These events track user progress through checklists, including task engagement and completions.

Example:

{
  "event_name": "checklist:10:SEEN",
  "attributes": {
    "interaction_id": "checklist_10",
    "is_dismissed": "",
    "parent_id": "",
    "status": "SEEN",
  }
}

Resource Center and Articles (resource_center , resource_center_article events)

These events capture user interactions with the resource center or specific articles within it.

Example:

{
  "event_name": "resource_center_article:6FAA69EBAFEEDF5E641ACF6D52847FC98AC44437591FC39D8BE67BDCF4570023:ENGAGED",
  "attributes": {
    "article_title": "How to Delete a Flow - Userpilot Knowledge Base",
    "article_url": "<https://docs.userpilot.com/article/224-how-to-delete-a-flow>",
    "interaction_id": "resource_center_article_6FAA69EBAFEEDF5E641ACF6D52847FC98AC44437591FC39D8BE67BDCF4570023",
    "is_dismissed": "0",
    "parent_id": "resource_center_1",
    "status": "ENGAGED"
  }
}

NPS Events

These events capture feedback from users through NPS surveys, including scores, feedback, and follow-up questions.

Example:

{
  "event_name": "nps:1:SUBMITTED_FEEDBACK",
  "attributes": {
    "feedback": "Great tool, highly recommended!",
    "follow_up_question": "Is there anything else we can improve?",
    "interaction_id": "nps_1",
    "score": "9",
    "status": "COMPLETED",
    "submission_id": "2024-05-02",
    "survey_question": "How likely is it that you would recommend us to a friend or colleague?"
  }
}

Flow and Flow Steps (experience , experience_step events)

These events track user interactions with experiences, such as onboarding or tutorials.

Example:

{
  "event_name": "experience:493:DISMISSED",
  "attributes": {
    "interaction_id": "experience_493",
    "is_dismissed": "1",
    "status": "DISMISSED",
    "total_dismissed": "1"
  }
}

🏛️ Key Data Entities & Relationships

• Users: Identified by user_id , with metadata (traits like email , signup_at , plan_type ).
• Companies: (B2B) Identified by company_id , with properties (e.g., company_name , industry ).
• Events: Actions or occurrences, each as a JSON line.
• Sessions: Grouped events within a continuous user activity period, identified by session .

Relationships

• A User can perform many Events.
• Multiple Events can occur within a single Session.
• A User may belong to one Company.

If you encounter any problems or have questions not covered in this documentation, please reach out to the Userpilot support team through your usual support channels (e.g., in-app chat, email support@userpilot.com).

Provide as much detail as possible about your issue for a faster resolution.