Skip to main content

Event entity

Events are a type of entity. An event represents a single occurrence of a specific customer action related to a customer session or a customer profile.

For example, a user updating their cart is considered a single event.

There are 2 types of events:

Built-in events

Built-in events are provided by Talon.One and are tied to a customer session or a customer profile. They are triggered depending on the endpoints used by your integration, and by the content of the requests.

Example

When your integration layer calls the Update customer session endpoint, for instance when a customer adds an item to their cart, an implicit talon_session_updated event happens.

Each event is related to a state:

States and events

See Customer session states.

Event name
(Rule Builder event type)
Trigger criteria for the eventTriggered by
talon_session_created
(Customer Session Creation)
A new session integration ID is sent to Talon.One so a new session is created. The state property becomes either open or closed.

Example: The customer creates a cart.
Update customer session
talon_session_updated
(Customer Session Update)
An open session was updated. The state property remains open.

Example: The customer adds an item to the cart.
Update customer session
talon_session_closed
(Customer Session Closing)
An open session was closed. The state property becomes closed.

Example: The customer completes the payment step.
Update customer session
talon_session_cancelledAn open session was cancelled. The state property becomes cancelled.

Example: The customer leaves before checkout.
Update customer session
talon_session_revokedA closed session was cancelled. The state property becomes cancelled.

Example: The customer requests a refund.
Update customer session
talon_session_partially_returnedA closed session had some items returned. The state property becomes partially_returned.

Example: The customer returns some of the items and expects the corresponding refund.
Return cart items
talon_session_reopenedA closed session was reopened. The state property becomes open.

Example: The closed order has to be modified after payment was processed.
Reopen customer session
talon_profile_created
(Customer Profile Registration)
A new customer integration ID is sent to Talon.One.Update customer profile with runRuleEngine=true
talon_profile_updated
(Customer Profile Update)
An existing customer profile was modified.Update customer profile with runRuleEngine=true

Custom events

Custom events are created by you. They contain custom attributes. Custom events cannot be canceled.

You can send these events with the Track Event endpoint and use them in the Rule Builder.

Example

You create an event that triggers when a user visits a page. Let's imagine that this event contains a custom url attribute. When the event is triggered for a given customer session, the url attribute and its value are added to the customer session. You can then use this attribute in the Rule Engine and Integration API.

important

A built-in event may readily fit your business scenario. Review the list of available built-in events before creating custom events.

Creating a custom event

A custom event contains one or more attributes. Even if you do not need an attribute in your use case, the event you create must contain one.

To create a custom event, create a custom attribute of type event, it will also automatically create an attribute:

  1. Open your Application.

  2. Click Account > Tools > Attributes > Create Attribute.

  3. In Associated Entity, select Event.

  4. In Event type, type a new value. This is the event name.

  5. In Attribute type, select the type of the attribute.

  6. In API Name, enter the name of the attribute contained in the event.

    Example

    To have a pageview event that contains a url attribute, Event type is pageview, API Name is url.

  7. Fill the other fields as needed and click Create Attribute.

The event now automatically contains a first attribute of the type and API name you just chose. You can now trigger the event or add more attributes to this event. To add more attributes, repeat the procedure, but ensure you always use the same value for Event type.

For more information about custom attributes, see Attributes.

Triggering an event

After you have defined an event, the integration layer can trigger it via the Integration API's Track event endpoint and bind it to a given customer session.

To use the endpoint, ensure you know your event details such as the event type, API name, and the customer session.

For example, assuming we created a pageview event with the url API name, we can call the Track Event endpoint with the following payload:

curl -X POST -H 'Content-Type: application/json' \
-H 'Authorization: ApiKey-v1 953f4d85715c425cb48676' \
-d '{
"profileId": "myprofileid",
"type": "pageview",
"attributes": {
"url": "some value"
}
}' 'https://mycompany.europe-west1.talon.one/v2/events'

The response contains the effects triggered by the Rule Engine, and all the details of the session, such as cart items and session total.

Using an event in a rule

When the integration layer registers custom events with the Track Event endpoint, you can check specific events in a rule:

  1. In a rule, add the Check for event types condition.
  2. In Event type, select your event type. For example, pageview.
  3. In the next field, select one of the attributes of your event type. Click And... to check extra attributes of your event, if you have any.
  4. Finish your rule by setting an effect and save.

Whenever the selected event type is triggered, the rule is evaluated.

Displaying triggered events

See Displaying events in the product docs.