Eve library

OSHUN Analytics Event Dictionary

Guide

Revision 1

On this page

Canonical event definitions for the OSHUN platform. Naming follows ADR-0006: <namespace>.<entity>.<action> (dot-delimited, lowercase, snake_case words).


Event Envelope (Required Fields)#

Every event MUST include the following envelope fields:

Field Type Description
event_id string Globally unique ID (evt_<random>)
event_name string Canonical dot-delimited name
event_version integer Schema version, starts at 1
occurred_at string ISO-8601 UTC timestamp
platform enum ios, android, web, pwa, server
surface enum mobile_shell, web_shell, domain_app, bff
session_id string Client session identifier
domain_context enum oshun_shell, tara, veritas, nyx, arete
consent_analytics boolean Whether user has granted analytics consent
user_id string? Authenticated user ID (if available)
anonymous_id string? Anonymous device/session ID (if no user_id)
app_version string? Application version string
locale string? User locale (e.g. en-US)

At least one of user_id or anonymous_id MUST be present.


Lifecycle Events#

oshun.app.opened#

Fired when the OSHUN shell starts up.

Property Type Description
entry enum cold or warm
startup_ms integer Time from process start to first frame
had_font_error boolean Whether custom fonts failed to load

oshun.app.backgrounded#

Fired when the app moves to the background.

Property Type Description
session_ms integer Duration of the foreground session
active_tab string Tab visible when backgrounded

oshun.app.resumed#

Fired when the app returns from background.

Property Type Description
background_ms integer Time spent in background

Authentication Events#

oshun.auth.completed#

Fired when a user signs in or signs up.

Property Type Description
method enum email, google, apple, github, other
is_new boolean Whether this was a new registration
source string Screen that initiated auth (onboarding, settings, paywall)

oshun.auth.signed_out#

Fired when a user signs out.

Property Type Description
reason enum user, session_expired, forced

oshun.auth.token_refreshed#

Fired when an access token is silently refreshed.

Property Type Description
success boolean Whether the refresh succeeded
latency_ms integer Round-trip time for the refresh request

Onboarding Events#

oshun.onboarding.started#

Fired when the onboarding flow begins.

Property Type Description
source enum first_launch, account_created, forced

oshun.onboarding.step_completed#

Fired when an onboarding step is completed.

Property Type Description
step_name string Name of the step (welcome, domains, preferences, notifications)
step_index integer 0-based step index
total_steps integer Total steps in the flow
duration_ms integer Time spent on this step

oshun.onboarding.completed#

Fired when onboarding finishes.

Property Type Description
total_duration_ms integer Total time spent in onboarding
steps_completed integer Number of steps completed
steps_skipped integer Number of steps skipped
domains_selected string[] Domains the user chose to enable

oshun.onboarding.abandoned#

Fired when the user exits onboarding without completing.

Property Type Description
last_step string The last step viewed before abandoning
step_index integer 0-based index of the last step
duration_ms integer Total time before abandoning

oshun.tab.viewed#

Fired when a tab becomes visible.

Property Type Description
tab enum home, explore, activity, profile
route string Full route path
transition_ms integer Navigation transition time

oshun.route.transitioned#

Fired on every route change.

Property Type Description
from_route string? Previous route (null on first load)
to_route string Destination route
transition_ms integer Navigation transition time
source enum app_start, navigation, deep_link

oshun.domain.launched#

Fired when a domain module is opened from the shell.

Property Type Description
domain enum tara, veritas, nyx, arete
source enum home, explore, deep_link, notification, search
latency_ms integer Time to domain-ready state
success boolean Whether the launch succeeded

Engagement Events#

oshun.item.saved#

Fired when a user saves/bookmarks content.

Property Type Description
domain enum tara, veritas, nyx, arete, nisaba
item_id string Domain-specific item identifier
item_type string Canonical saved object type (meditation, claim, source, passage, notebook, sky-event)
source enum? Optional origin surface: home, explore, assistant, library
surface enum? Optional UI surface: panel, dashboard, results-page, message, saved-items
target_path string? Optional launch path captured for the saved item
query_length integer? Optional query length when the save happened from search
result_count integer? Optional rendered result count when the save happened from search
position integer? Optional rendered result position when the save happened from search

oshun.item.unsaved#

Fired when a user removes a bookmark.

Property Type Description
domain enum tara, veritas, nyx, arete, nisaba
item_id string Domain-specific item identifier
item_type string Canonical saved object type (meditation, claim, source, passage, notebook, sky-event)
source enum? Optional origin surface: home, explore, assistant, library
surface enum? Optional UI surface: panel, dashboard, results-page, message, saved-items
target_path string? Optional launch path captured for the unsaved item
query_length integer? Optional query length when the unsave happened from search
result_count integer? Optional rendered result count when the unsave happened from search
position integer? Optional rendered result position when the unsave happened from search

oshun.activity.reentry_opened#

Fired when a user follows a re-entry affordance from the Activity timeline.

Property Type Description
surface enum timeline
trigger enum thread, step, assistant-highlight, study-continuation
target_kind enum domain, library, workspace, shell
target_path string Destination path opened from Activity
primary_domain enum tara, veritas, nyx, arete, nisaba
item_domain enum tara, veritas, nyx, arete, nisaba
thread_id string Continuity thread identifier
thread_position integer 0-based position of the rendered thread within the filtered timeline
step_id string? Timeline step identifier when the re-entry came from a step-level affordance
step_position integer? 0-based position of the step within its continuity thread
item_id string Logical entity identifier for the clicked affordance
item_type string Logical entity kind (continuity-thread, note, assistant-highlight, etc.)
unread_count integer Unread step count remaining in the continuity thread
thread_step_count integer Total number of steps inside the continuity thread
domain_filter enum all, tara, veritas, nyx, arete, nisaba
kind_filter enum all, update, reminder, event, insight
is_cross_domain boolean Whether the continuity thread spans more than one domain

oshun.item.resumed#

Fired when a user resumes previously started content.

Property Type Description
domain enum tara, veritas, nyx, arete
item_id string Domain-specific item identifier
item_type string Content type
progress_pct number Progress percentage at resume time (0-100)

oshun.value_action.completed#

Normalized high-value action for KPI computation.

Property Type Description
domain enum tara, veritas, nyx, arete
value_action_type string Action type (meditation_completed, article_read, observation_logged, checkin_completed)
completion_quality enum partial, full
entity_id string Domain entity reference

Search Events#

oshun.search.executed#

Fired when a search query is submitted.

Property Type Description
query_length integer Character count of the query
source enum home, explore, bff
surface enum results, suggestions
result_count integer Number of results returned
domain_filter enum all, tara, veritas, nyx, arete
partial_failure boolean Whether any domain backend failed

oshun.search.zero_results#

Fired when a search returns no results.

Property Type Description
query_length integer Character count of the query
source enum home, explore, bff
surface enum results, suggestions
domain_filter enum all, tara, veritas, nyx, arete

oshun.search.result_opened#

Fired when a search result is tapped.

Property Type Description
domain enum tara, veritas, nyx, arete
item_id string ID of the opened item
item_type string Content type of the result
position integer 0-based position in results list
query_length integer Length of the original query

Notification Events#

oshun.notification.received#

Fired when a push notification is received.

Property Type Description
domain enum oshun, tara, veritas, nyx, arete
kind string Notification kind
channel enum push, in_app, email

oshun.notification.opened#

Fired when a notification is opened/actioned.

Property Type Description
domain enum oshun, tara, veritas, nyx, arete
kind string Notification kind
latency_ms integer Time from receive to open
source enum banner, center, push_tap

oshun.notification.dismissed#

Fired when a notification is dismissed without action.

Property Type Description
domain enum oshun, tara, veritas, nyx, arete
kind string Notification kind

Recommendation Events#

oshun.recommendation.impressed#

Fired when recommendation cards are visible.

Property Type Description
count integer Number of recommendations shown
domains string[] Domains represented in visible set
source string Source screen (e.g. home)

oshun.recommendation.tapped#

Fired when a recommendation is tapped.

Property Type Description
item_id string ID of the recommended item
domain enum tara, veritas, nyx, arete
item_type string Content type
position integer Position in carousel
reason string Recommendation reason category
score number Composite relevance score

oshun.recommendation.feedback#

Fired when a user gives feedback on a recommendation.

Property Type Description
item_id string ID of the item
domain enum tara, veritas, nyx, arete
signal enum hide, less, more

Performance Events#

oshun.performance.startup#

Fired once per app session with startup metrics.

Property Type Description
cold_start boolean Whether this was a cold start
time_to_interactive_ms integer Time until first interaction ready
js_bundle_ms integer JS bundle load time
native_init_ms integer Native layer initialization time

oshun.performance.web_vitals#

Fired on web/PWA with Core Web Vitals.

Property Type Description
lcp_ms number Largest Contentful Paint in ms
fid_ms number First Input Delay in ms
cls number Cumulative Layout Shift score
ttfb_ms number Time to First Byte in ms
inp_ms number Interaction to Next Paint in ms
route string Route on which vitals were captured

Error Events#

oshun.error.boundary_triggered#

Fired when an error boundary catches an exception.

Property Type Description
component string Component tree path
message string Error message (PII-scrubbed)
recovered boolean Whether the user chose to retry

oshun.error.api_failure#

Fired when a BFF/API request fails.

Property Type Description
endpoint string Sanitized endpoint path
status_code integer HTTP status code (0 for network errors)
latency_ms integer Request duration
retried boolean Whether a retry was attempted

Commerce Events#

oshun.paywall.viewed#

Fired when a paywall/upgrade prompt is displayed.

Property Type Description
source string Screen that triggered the paywall
tier enum free, pro, premium

oshun.purchase.started#

Fired when a purchase flow begins.

Property Type Description
product_id string Product/plan identifier
tier enum pro, premium
source string Screen that initiated purchase

oshun.purchase.completed#

Fired when a purchase succeeds.

Property Type Description
product_id string Product/plan identifier
tier enum pro, premium
amount_usd number Purchase amount in USD cents
trial boolean Whether this is a trial conversion

Tara Domain Events#

tara.session.started#

Property Type Description
meditation_id string Meditation content ID
category string Meditation category
duration_sec integer Expected session duration

tara.session.completed#

Property Type Description
meditation_id string Meditation content ID
active_listen_sec integer Actual listened duration
completed_full boolean Whether played to end

tara.session.abandoned#

Property Type Description
meditation_id string Meditation content ID
progress_pct number Progress at abandonment (0-100)
active_listen_sec integer Actual listened duration

Veritas Domain Events#

veritas.article.viewed#

Property Type Description
article_id string Article identifier
topic string Primary topic
source enum feed, search, notification, deep_link

veritas.article.read_depth#

Property Type Description
article_id string Article identifier
depth_pct integer Read depth percentage (25, 50, 75, 100)
read_time_ms integer Time spent reading

veritas.topic.followed#

Property Type Description
topic_id string Topic identifier
source enum article, search, settings

Nyx Domain Events#

nyx.sky_event.viewed#

Property Type Description
event_id string Sky event identifier
event_type string Event category (meteor_shower, eclipse, conjunction)

nyx.observation.logged#

Property Type Description
object_id string Celestial object identifier
object_type string Object type (star, planet, galaxy)
has_notes boolean Whether user added notes

nyx.sky_map.opened#

Property Type Description
ar_mode boolean Whether AR mode was activated
source enum home, explore, event_detail

Arete Domain Events#

arete.checkin.completed#

Property Type Description
duration_sec integer Time to complete check-in
mood_recorded boolean Whether mood was recorded
reflection boolean Whether a journal reflection was added

arete.goal.created#

Property Type Description
horizon enum short, mid, long
category string Goal category

arete.habit.streak_updated#

Property Type Description
habit_id string Habit identifier
streak_days integer Current streak length
longest_streak integer All-time longest streak

Retention Funnel#

The following events form the core retention funnel for KPI tracking:

  1. oshun.app.opened - User opens the app
  2. oshun.auth.completed - User authenticates (or skips for anonymous)
  3. oshun.onboarding.completed - User completes onboarding
  4. oshun.domain.launched - User enters a domain
  5. oshun.value_action.completed - User completes a high-value action
  6. oshun.item.saved - User saves content (engagement signal)

Activation Definition#

A user is activated when they have completed at least one oshun.value_action.completed event within their first 7 days.

Retention Definition#

A user is retained when they fire at least one oshun.app.opened event in a given measurement window (D1, D7, D14, D30).


Data Quality Rules#

  1. Required fields: All envelope fields must be present. Events missing event_id, event_name, occurred_at, platform, or session_id are rejected.
  2. Name format: Event names must match ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2}$.
  3. Consent gate: Events with consent_analytics=false are excluded from KPI aggregation.
  4. Timestamp bounds: occurred_at must be within 24 hours of server receive time.
  5. Deduplication: Events with duplicate event_id within a 1-hour window are dropped.
  6. Cardinality limits: String properties with >1000 unique values per day are flagged for review.