Event Schemas

This section provides details on the structure of the different event types sent by LasoExperience to third-party webhook endpoints.

Common Event Properties

All events sent by LasoExperience to third-party webhooks include these standard properties:

Property	Type	Description
event	string	The type of event (e.g., activity_view, user_login, screen_view)
time	number	Unix timestamp in milliseconds when the event occurred
propertyId	string	Internal identifier for the LasoExperience property
distinctId	string	Unique identifier for the user
insertId	string	Unique identifier for each event instance, used to ensure idempotent processing
sessionId	string	Unique identifier for the user's session
deviceMetadata	object	Information about the user's device, session, app, and network
metadata	object	Additional context data including browser, device, OS, IP address, and referrer information
payload	object	Optional. Event-specific data that varies by event type

Device Metadata Object

The deviceMetadata object contains detailed information about the user's device and context:

Property	Type	Description
device	object	Device information including model, brand, OS, screen dimensions
network	object	Network information including type and connectivity status
app	object	App information including version, build number, and install details
session	object	Session information including duration and start time
platform	string	Platform identifier (web, ios, android)
timestamp	string	ISO timestamp of when the metadata was collected
sessionId	string	Unique identifier for the user's session
sessionStartTime	number	Unix timestamp when the session started
sessionDuration	number	Duration of the session in milliseconds

Metadata Object

The metadata object provides additional context about the event, particularly for web events:

Property	Type	Description
ua	string	User agent string
browser	object	Browser information including name, version, and major version
device	object	Device information including model and vendor
engine	object	Browser engine information including name and version
os	object	Operating system information including name and version
ipAddress	string	IP address of the client
location	object	Geographic location information derived from IP address
referer	string	URL of the referring page
acceptLanguage	string	Accept-Language HTTP header value
pageType	string	Type of page where the event occurred
url	string	URL of the page where the event occurred
contentZones	array	List of content zones on the page
time	number	Unix timestamp in milliseconds when the event occurred
surveyId	string	ID of the survey if the event is related to a survey
surveyStartTime	string	Time when the survey started

Event Types

LasoExperience sends various event types that capture different user interactions. Here are the main event types:

User Login Event

Triggered when a user logs into the application.

{
  "event": "user_login",
  "time": 1741717450350,
  "propertyId": "gnoml4IQloqBqyfX9aIP",
  "distinctId": "user-123",
  "insertId": "1741717450350-a1b2c3d4e5f6",
  "sessionId": "session-123",
  "deviceMetadata": {
    "device": {
      "deviceId": "device-123",
      "deviceType": "smartphone",
      "brand": "Apple",
      "os": "iOS",
      "manufacturer": "Apple",
      "model": "iPhone 13",
      "deviceName": "iPhone 13",
      "systemName": "iOS",
      "systemVersion": "15.4",
      "readableVersion": "15.4",
      "isTablet": false,
      "isEmulator": false,
      "hasNotch": true,
      "firstInstallTime": 1643723400,
      "lastUpdateTime": 1643723400,
      "timezone": {
        "calendar": "gregorian",
        "timeZone": "America/New_York"
      },
      "screenDimensions": {
        "width": 1080,
        "height": 2536,
        "scale": 3,
        "fontScale": 1,
        "resolution": "1080x2536"
      }
    },
    "network": {
      "isConnected": true,
      "isInternetReachable": true,
      "type": "wifi",
      "details": {}
    },
    "app": {
      "appName": "LasoExperience",
      "appVersion": "1.0.0",
      "buildNumber": "1",
      "bundleId": "com.lasoxp.lasoxperience",
      "installReferrer": "",
      "firstInstallTime": 1643723400,
      "lastUpdateTime": 1643723400,
      "uptime": 3600
    },
    "session": {
      "sessionId": "session-123",
      "startTime": 1643723400,
      "duration": 3600
    },
    "platform": "ios",
    "timestamp": "2022-02-01T12:00:00.000Z"
  },
  "metadata": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36",
    "browser": {
      "name": "Chrome",
      "version": "134.0.0.0",
      "major": "134"
    },
    "device": {
      "model": "Macintosh",
      "vendor": "Apple"
    },
    "engine": {
      "name": "Blink",
      "version": "134.0.0.0"
    },
    "os": {
      "name": "macOS",
      "version": "10.15.7"
    },
    "ipAddress": "185.124.240.162",
    "location": {
      "country": "US",
      "region": "CA",
      "timezone": "America/Los_Angeles",
      "city": "San Francisco",
      "ll": {
        "0": 37.7794,
        "1": -122.4176
      },
      "metro": 807,
      "area": 1000
    },
    "referer": "https://sunseeker.app.lasoxp.com/"
  },
}

Screen View Event

Triggered when a user navigates to a different screen or page in the application.

{
  "event": "screen_view",
  "time": 1741717442708,
  "propertyId": "gnoml4IQloqBqyfX9aIP",
  "distinctId": "user-123",
  "insertId": "1741717442708-b2c3d4e5f6g7",
  "sessionId": "session-123",
  "deviceMetadata": {
    // Device metadata object as described above
  },
  "payload": {
    "os": "web",
    "path": "Home"
  }
}

For screen views with parameters:

{
  "event": "screen_view",
  "time": 1741717441642,
  "propertyId": "gnoml4IQloqBqyfX9aIP",
  "distinctId": "user-123",
  "insertId": "1741717441642-c3d4e5f6g7h8",
  "sessionId": "session-123",
  "deviceMetadata": {
    // Device metadata object as described above
  },
  "payload": {
    "os": "web",
    "params": {
      "mapId": "QZFqV2lntUdoceywkshI"
    },
    "path": "PropertyMap"
  }
}

Activity View Event

Triggered when a user views a specific activity.

{
  "event": "content_view_activity",
  "time": 1741717436538,
  "propertyId": "gnoml4IQloqBqyfX9aIP",
  "distinctId": "user-123",
  "insertId": "1741717436538-d4e5f6g7h8i9",
  "sessionId": "c44e852b-d0bf-4d91-b5b6-1f2f33a00f2d",
  "deviceMetadata": {
    // Device metadata object as described above
  },
  "metadata": {
    // Metadata object as described above
  },
  "payload": {
    "activity": {
      "id": "c3b1b5f8-f673-4bae-9bdf-d68c6ddd001d",
      "title": "Grand View Spa",
      "type": "Activity"
    },
    "os": "web",
    "refId": "c3b1b5f8-f673-4bae-9bdf-d68c6ddd001d",
    "reservationId": "20250804"
  }
}

Event View Event

Triggered when a user views a specific event.

{
  "event": "event_view",
  "time": 1741717430649,
  "propertyId": "gnoml4IQloqBqyfX9aIP",
  "distinctId": "user-123",
  "insertId": "1741717430649-e5f6g7h8i9j0",
  "sessionId": "session-123",
  "deviceMetadata": {
    // Device metadata object as described above
  },
  "metadata": {
    // Metadata object as described above
  },
  "payload": {
    "event": {
      "id": "0be7e433-494c-48ba-99a2-424d870f3f1c",
      "title": "Promenade Walk/Run",
      "type": "Event"
    },
    "os": "web",
    "refId": "0be7e433-494c-48ba-99a2-424d870f3f1c",
    "reservationId": "MZ202407032152"
  }
}

Home CTA Click Event

Triggered when a user clicks on a call-to-action on the home screen.

{
  "event": "home_cta_click",
  "time": 1741717450350,
  "propertyId": "gnoml4IQloqBqyfX9aIP",
  "distinctId": "user-123",
  "insertId": "1741717450350-f6g7h8i9j0k1",
  "sessionId": "session-123",
  "deviceMetadata": {
    // Device metadata object as described above
  },
  "metadata": {
    // Metadata object as described above
  },
  "payload": {
    "contentblockrowwithimage": {
      "active": true,
      "description": "Relax in coastal comfort as you navigate the resort with ease",
      "id": "2c0247d9-feda-413b-bd40-9542fcf499b0",
      "image": {
        "alt": "Resort Map",
        "src": "https://assets.lasoxp.com/sunhotels/sunhotels_resort_map.jpeg"
      },
      "link": "https://assets.lasoxp.com/sunhotels/sunhotels_resort_map.jpeg",
      "title": "Resort Map",
      "type": "ContentBlockRowWithImage"
    },
    "os": "web",
    "refId": "2c0247d9-feda-413b-bd40-9542fcf499b0"
  }
}

Content blocks can also be of type ContentBlockRowWithIcon:

{
  "event": "home_cta_click",
  "time": 1741717445649,
  "propertyId": "gnoml4IQloqBqyfX9aIP",
  "distinctId": "user-123",
  "insertId": "1741717445649-g7h8i9j0k1l2",
  "sessionId": "session-123",
  "deviceMetadata": {
    // Device metadata object as described above
  },
  "metadata": {
    // Metadata object as described above
  },
  "payload": {
    "contentblockrowwithicon": {
      "active": true,
      "description": "5500 sunhotels Way, Charlotte Harbor, FL 33980",
      "displayCondition": "ALWAYS",
      "iconName": "navigate-circle-outline",
      "id": "36923006-b6cf-413a-936a-72bccc1f0a3e",
      "link": "https://www.google.com/maps/place/sunhotels+Resort+Charlotte+Harbor",
      "title": "Find us",
      "type": "ContentBlockRowWithIcon"
    },
    "os": "web",
    "refId": "36923006-b6cf-413a-936a-72bccc1f0a3e"
  }
}

Payload Structure

The payload object varies by event type but typically includes:

Property	Type	Description
os	string	Platform where the event occurred (e.g., "web", "ios", "android")
path	string	For screen_view events, the screen/page name
params	object	Optional. Additional parameters for the screen/page
refId	string	Reference ID for the viewed or clicked item
reservationId	string	Optional. ID of the associated reservation
activity	object	For activity_view events, details about the activity
event	object	For event_view events, details about the event
contentblockrowwithimage	object	For home_cta_click events with image content
contentblockrowwithicon	object	For home_cta_click events with icon content

Event Processing

Events go through several processing steps before being delivered:

1. Session Management:

   • Sessions are created with unique IDs
   • Session timeout after 30 minutes of inactivity
   • Session duration and start time are tracked

2. Device Metadata Collection:

   • Basic device info is always collected
   • Full metadata collection is optional and configurable
   • Some fields may be platform-specific (web vs mobile)

3. Data Transformation:

   • Only string and number values are included
   • Sensitive data is masked

4. Delivery:

   • Events are sent in real-time
   • Multiple delivery endpoints may receive the same event
   • Each delivery is independent and atomic

Best Practices

1. Session Handling:

   • Track session IDs for user journey analysis
   • Consider session duration for timing-based features
   • Handle session timeouts appropriately

2. Device Metadata:

   • Use device metadata for platform-specific features
   • Consider screen dimensions for UI optimization
   • Check network status for offline capabilities

3. Data Processing:

   • Implement proper data validation
   • Consider data volume during peak times

Validating Events

We recommend validating incoming events against these schemas to ensure proper processing. You can use JSON Schema validation libraries in your webhook endpoint implementation.

Event Frequency and Volume

Events are sent in real-time as they occur. The volume of events will depend on your user activity. You should design your webhook endpoint to handle bursts of traffic during peak usage periods.

Handling Duplicate Events

Your webhook endpoint should be idempotent, as in rare cases the same event might be delivered more than once. You can use the insertId field to implement deduplication logic, as this field is guaranteed to be unique for each event instance. By storing processed insertId values, you can easily identify and skip duplicate events.