Customer behavior and user events

Use the search bar or the checkboxes below to find the events you need to use Currents effectively.

These schema include other App or Website activity such as Sessions, Custom Events, and Purchases tracked through the platform.

Contact your Braze representative or open a support ticket if you need access to additional event entitlements. If you can’t find what you need in this article, check out our Message Engagement Events Library or our Currents sample data examples.

Explanation of customer behavior and user event structure and platform values

Event structure

This customer behavior and user events breakdown shows what type of information is generally included in a customer behavior or user event. With a solid understanding of its components, your developers and business intelligence strategy team can use the incoming Currents event data to make data-driven reports, charts and take advantage of other valuable data metrics.

Breakdown of a user event showing a purchase event with the listed properties grouped by user-specific properties, behavior-specific properties, and device-specific properties

Customer behavior and user events are comprised of user-specific properties, behavior-specific properties, and device-specific properties.

Platform values

Certain events return a platform value that specifies the platform of the user’s device.
The following table details the possible returned values:

User device	Platform value
iOS	`ios`
Android	`android`
FireTV	`kindle`
Kindle	`kindle`
Web	`web`
tvOS	`tvos`
Roku	`roku`

important:

Note that these schemas only apply to the flat file event data we send to Data Warehouse partners (Google Cloud Storage, Amazon S3, and Microsoft Azure Blob Storage), and are not available for Segment connectors. For schema that apply to other partners, refer to our list of available partners and check their respective pages.

Additionally, note that Currents will drop events with excessively large payloads of greater than 900 KB.

Custom events

This event occurs when a specific custom event is triggered. Use this to track when users perform custom events in your application.

// Custom Event: users.behaviors.CustomEvent
{
  "id": (required, string) unique ID of this event,
  "app_group_id": (required, string) Braze ID of the workspace this user belongs to,
  "user_id": (required, string) Braze user ID of the user,
  "external_user_id": (optional, string) External ID of the user,
  "app_id": (optional, string) ID for the app on which the user action occurred,
  "time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
  "timezone": (optional, string) IANA time zone of the user at the time of the event,
  "platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
  "os_version": (optional, string) os version of device used for the action,
  "device_model": (optional, string) hardware model of the device,
  "device_id": (optional, string) ID of the device on which the event occurred,
  "name": (required, string) name of the custom event,
  "properties": (required, string) JSON encoded string of the properties for this event,
  "ad_id": (optional, string) advertising identifier,
  "ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
  "ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}

Property details

For ad_id, ad_id_type and ad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ad ID through the native SDKs. Learn more about them here: iOS, Android.
If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending ad_id.

Purchase event

This event occurs when a user makes a purchase. Use this data to track when users purchase something in the application.

tip:

Purchases are special custom events and come with a JSON encoded string of custom event properties the same way custom events do.

// Purchase Event: users.behaviors.Purchase
{
  "id": (required, string) unique ID of this event,
  "app_group_id": (required, string) Braze ID of the workspace this user belongs to,
  "user_id": (required, string) Braze user ID of the user,
  "external_user_id": (optional, string) External ID of the user,
  "app_id": (optional, string) ID for the app on which the user action occurred,
  "time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
  "platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
  "os_version": (optional, string) os version of device used for the action,
  "device_model": (optional, string) hardware model of the device,
  "device_id": (optional, string) ID of the device on which the event occurred,
  "product_id": (required, string) ID of the product purchased,
  "price": (required, float) price of the purchase,
  "currency": (required, string) three letter alpha ISO 4217 currency code,
  "properties": (required, string) JSON encoded string of the custom properties for this event,
  "ad_id": (optional, string) advertising identifier,
  "ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
  "ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}

Property details

For ad_id, ad_id_type and ad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ad ID through the native SDKs. Learn more about them here: iOS, Android.
If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending ad_id.

First session event

This event occurs when a user starts their first session in your application. Use this data to track when users start sessions.

tip:

When a user starts their first session, both a FirstSession and a SessionStart event are fired.

// Session Start: users.behaviors.app.FirstSession
{
  "id": (required, string) unique ID of this event,
  "app_group_id": (required, string) Braze ID of the workspace this user belongs to,
  "user_id": (required, string) Braze user ID of the user,
  "external_user_id": (optional, string) External ID of the user,
  "time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
  "timezone": (optional, string) IANA time zone of the user at the time of the event,
  "session_id": (required, string) ID of the session,
  "app_id": (required, string) ID for the app on which the user action occurred,
  "platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
  "os_version": (optional, string) os version of the device used for the action,
  "device_model": (optional, string) hardware model of the device,
  "device_id": (optional, string) ID of the device on which the session occurred,
  "gender": (optional, string) gender of the user (This field has been deprecated and will always return null),
  "country": (optional, string) country of the user (This field has been deprecated and will always return null),
  "language": (optional, string) language of the user (This field has been deprecated and will always return null),
  "sdk_version": (optional, string) version of the Braze SDK in use during the session (This field has been deprecated and will always return null)
}

Session start event

This event occurs when a user starts a session. Use this data to track when users start sessions.

tip:

When a user starts their first session, both a FirstSession and a SessionStart event are fired.

// Session Start: users.behaviors.app.SessionStart
{
  "id": (required, string) unique ID of this event,
  "app_group_id": (required, string) Braze ID of the workspace this user belongs to,
  "user_id": (required, string) Braze user ID of the user,
  "external_user_id": (optional, string) External ID of the user,
  "app_id": (required, string) ID for the app on which the user action occurred,
  "time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
  "session_id": (required, string) ID of the session,
  "platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
  "os_version": (optional, string) os version of the device used for the action,
  "device_model": (optional, string) hardware model of the device,
  "device_id": (optional, string) ID of the device on which the session occurred
}

End session event

This occurs when a user exits your application, therefore ending their current session. Use this data to track when sessions end, and along with the appropriate session start event, calculate the duration of their time in a session.

tip:

When a user starts their first session, both a FirstSession and a SessionStart event are fired.

// Session End: users.behaviors.app.SessionEnd
{
  "id": (required, string) unique ID of this event,
  "app_group_id": (required, string) Braze ID of the workspace this user belongs to,
  "user_id": (required, string) Braze user ID of the user,
  "external_user_id": (optional, string) External ID of the user,
  "app_id": (required, string) ID for the app on which the user action occurred,
  "time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
  "duration": (optional, float) seconds session lasted,
  "session_id": (required, string) ID of the session,
  "platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
  "os_version": (optional, string) os version of the device used for the action,
  "device_model": (optional, string) hardware model of the device,
  "device_id": (optional, string) ID of the device on which the session occurred
}

Location event

This event is triggered when a user visits a specified location. Use this to track users triggering location events in your app.

// Location Event: users.behaviors.Location
{
  "id": (required, string) unique ID of this event,
  "app_group_id": (required, string) Braze ID of the workspace this user belongs to,
  "user_id": (required, string) Braze user ID of the user,
  "external_user_id": (optional, string) External ID of the user,
  "app_id": (required, string) ID for the app on which the user action occurred,
  "time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
  "latitude": (required, float) latitude of recorded location,
  "longitude": (required, float) longitude of recorded location,
  "altitude": (optional, float) altitude of recorded location,
  "ll_accuracy": (optional, float) latitude/longitude accuracy of recorded location,
  "alt_accuracy": (optional, float) altitude accuracy of recorded location,
  "platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
  "os_version": (optional, string) os version of device used for the action,
  "device_model": (optional, string) hardware model of the device,
  "device_id": (optional, string) ID of the device on which the event occurred,
  "ad_id": (optional, string) advertising identifier,
  "ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
  "ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}

Property details

For ad_id, ad_id_type and ad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ad ID through the native SDKs. Learn more about them here: iOS, Android.
If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending ad_id.

Attribution events

This event occurs when an app installation is attributed to a source. Use this to track where your app installs are coming from.

// Install Attribution Event: users.behaviors.InstallAttribution
{
  "id": (required, string) unique ID of this event,
  "app_group_id": (required, string) Braze ID of the workspace this user belongs to,
  "user_id": (required, string) Braze user ID of the user,
  "external_user_id": (optional, string) External ID of the user,
  "time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
  "source": (required, string) the source of the attribution
}

Random bucket number event

This user event occurs every time a new user is created within their workspace. During this event, each new user gets assigned a random bucket number that you can then use to create uniformly distributed segments of random users. Use this to group a range of random bucket number values and compare performance across your campaigns and campaign variants.

// Random Bucket Number Event: users.RandomBucketNumberUpdate
{
  "id": (required, string) unique ID of this event,
  "app_group_id": (required, string) AppGroup API ID,
  "user_id": (required, string) Braze user ID of the user,
  "external_user_id": (optional, string) External ID of the user,
  "time": (required, int) UTC time of the event in milliseconds since the epoch,
  "random_bucket_number": (required, int) new random bucket number
  "prev_random_bucket_number":  (optional, int) old random bucket number, optional
}

important:

Note that this Currents event is only available for customers that have purchased an “all events connector” and is only available for storage event connectors (i.e Amazon S3, Microsoft Azure, Google Cloud Storage).

To get this event enabled and to schedule the backfill for existing users’ random bucket numbers in your workspace, contact your customer success manager.

Edit this page on GitHub

HOW HELPFUL WAS THIS PAGE?