Skip to main content

Events Dynamics

To able to incarnate a profile from raw events, you have to understand the relationship of Event-Session-Profile (E.S.P.) trinity.

The E.S.P. Model​

Events​

There are three type of events:

  • Behavioral events are behaviors initiated from a person, it represents actions that users took from real world.
  • Built-in events are events that have predefined behaviors by the system. A prominent example is identify event, where it's target's properties are extracted to out and update to the resolved profile.
  • System events or "reaction" events are ones that get generated within the system. Generally these events won't be visible on CDP web app.

Sessions​

Every events except system events always have a session_id attached along. This session_id is generated on the client side. Theoretically speaking, session_id logically groups logical events from a same physical person together. A person (or Profile) could have multiple sessions (from different clients/devices, or long gap between interactions from a same device (it's up the client side to decide the boundary between sessions).

Profiles​

A Profile is a representative object of a physical person. Profiles are bound with a collection of sessions and events. All of it traits and behaviors are inferred from its own events (it means there are no direct mutation on a profile object).

The relationship of these entities could be visualized as:

ESP Model

The Flow​

A typical flow to fabricate a profile is:

Step #1: First, send a identify event with a specific session ID. In the identify events, specify a PII (Personal Identifiable Information on the event's target.properties). The target's itemType must be "analyticsUser" for now (itemId — which usually comes in pair with itemType — can be skipped). An example of an identify event's payload:

{
    "eventType": "identify",
    "sessionId": "a-session-id"
    "target": {
        "itemType": "analyticsUser",
        "properties": {
            "email": "someone@gmail.com"
        }
    }

}

The PII in this example is email. Currently these properties are accepted as PII:

  • email
  • phone
  • cellphone
  • phone_number
  • device_id
  • id

Step #2: Secondly, send a desired behavioral events, a click for example:

{
    "eventType": "click",
    "sessionId": "a-session-id"  // The sessionId must be exactly the same as the identify event above
    "properties": {
        "clickedItem": "<some-element-id>",
        "currentUrl": "<some-page-url>"
    }

}

After those steps , 4 new entities will be ingested on inside the system:

  • 2 events (built-in event identify and behavioral event click).
  • 1 session with the ID of a-session-id.
  • 1 profile (actually if a profile with someone@gmail.com is already exists, no new profile is created, but that existing profile will be resolved and the session is bound to that profile).

Events Flow Example