Mobile and Web SDK Schema Quick Guide for Data Cloud
A Mobile and Web SDK schema is a collection of event definitions used in Data Cloud. You can find more examples of the schema in the API Developer Guide for Data Cloud.
Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.
When you upload a JSON schema for your mobile or web application connector, populate the six mandatory fields. If these fields are empty or missing in your JSON file, an error message appears and you're asked to reupload the schema with the correct data.
- deviceId
- eventId
- dateTime
- eventType
- category
- sessionId
For more information on how JSON data is structured, see the Data Cloud section of the Salesforce Interactions SDK.
Engagement and profile events are stored in the same structure. The event must contain a masterLabel, developerName, and category.
| Field Name | Description |
|---|
| masterLabel | - Convenient Event name for display purposes only.
- Limited to 80 characters.
- Allows spaces and most characters.
- Generally is the same as the developer name but with spaces and special characters.
|
| developerName | - Name of the Event used throughout the system. The developer must use these names when submitting events to the beacon.
- Must be a unique name across all events in the mobile, web, ingest API application.
- Limited to 80 characters. When used in a data stream, anything longer than 40 characters gets truncated with a hash.
- developerName is a Salesforce setup entity, so special characters aren’t allowed. Alphanumeric only. Must start with a letter.
- Non-Salesforce supported developer names are updated to satisfy name requirements. Spaces are replaced with '_', and so on.
|
| category | Engagement or Profile. |
This table shows the basic definition of the event field components.
| Field Name | Required or Optional | Description |
|---|
| dataType | Required | - Three options: Text, DateTime, Number
- date field values must be ISO8601 format (
yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
|
| masterLabel | Required | - Convenient Event name for display purposes only.
- Limited to 80 characters.
- Allows spaces and most characters.
|
| developerName | Required | - The name of the Event Field and must be unique across all fields in the same event.
- Limited to 80 characters.
- developerName is a Salesforce Setup entity, so special characters aren't allowed.
- Alphanumeric only. Must start with a letter.
- Non-Salesforce supported developer names are updated to satisfy name requirements. That is, spaces are replaced with '_', and so on.
|
| DeviceManufacturer | Optional | - Derived from user agent string for device manufacturer
- Apple or Samsung
|
| IsBrowser | Optional | - Derived from user agent string for browser
- Boolean
|
| BrowserName | Optional | - Derived from user agent string for browser name
- Such as Safari or Microsoft Edge
|
| BrowserRenderEngine | Optional | - Derived from browser rendering engine for user agent data
- WebKit, WebKit/Blink, or EdgeHTML/Blink
|
| BrowserVendor | Optional | - Derived from user agent string for browser vendor
- Apple, Samsung, or Microsoft
|
| BrowserVersion | Optional | - Derived from user agent string for
- browser version number
- For example, 17.4.1
|
| DeviceModel | Optional | - Derived from user agent string for device model
- iPhone, Mac, or Galaxy S10
|
| DeviceType | Optional | - Derived from user agent string for device type
- Smartphone or Desktop
|
| OSFamily | Optional | - Derived from user agent string for OS family
- iOS, macOS, or Android
|
| OSVendor | Optional | - Derived from user agent string for
- OS vendor
- Apple, Google, or Microsoft Corporation
|
| OSVersion | Optional | - Derived from user agent string for OS version number
- Such as IOS 17 or Android 12
|
| UserAgent | Optional | - Derived from raw user agent for user agent data
|
| isDataRequired | Optional | - Defaults to false when not indicated
- When true, it indicates that this field must be sent when the parent event is sent to the beacon.
|
| primaryIndexOrder | Optional | - Value must be 1 for the event field that's used as a primary key.
- Value is important when mapping data stream DLO to DMO entities.
- Be careful with engagement events because all engagement events are combined into a single DLO. Set all engagement event schemas to the same field as primaryIndexOrder.
|
There are six specially named event fields that must be included for all engagement and profile event schemas. The schema fails to be imported without these field developer names. All field names are text except for dataTime.
| Event Field | Field type | Notes |
|---|
| deviceId | text | Usually the primary key for profile events. |
| eventId | text | Usually the primary key for engagement events. |
| dateTime | datetime | Especially important for engagement events, which also are used for data partitioning. Supports ISO8601 format only. |
| eventType | text | |
| category | text | |
| sessionId | text | |
Schemas must be backwards-compatible. After a schema is uploaded, the user:
- Can't update their schema by adding a new required field (breaks backwards compatibility).
- Can't update or rename any existing field.
- Can add new optional (isDataRequired=false) fields to an existing schema.