Skip to main content

Events

Events are a type of entity. An event represents a single occurrence of a specific customer action, and it is always connected to a customer session.

Just like attributes, there are 2 types of events:

  • Built-in events
  • Custom events

Built-in events

Built-in events are provided by Talon.One and are tied typically to the customer session or customer profile. One of the following events may be triggered based on the properties of the request received by Talon.One:

  • When the Update customer session endpoint receives a request:

    Event name
    (Rule Builder event type)
    Trigger criteria for the event
    talon_session_created
    (Customer Session Creation)
    • The state property is either open or closed.
    • The request includes a new integration ID.
    Example: The customer creates a cart.
    talon_session_updated
    (Customer Session Update)
    The state property is open.

    Example: The customer adds an item to the cart.
    talon_session_closed
    (Customer Session Closing)
    The state property is closed.

    Example: The customer checks out.
    talon_session_cancelled
    • The state property is cancelled.
    • In the preceding request, the state property was open.

    Example: The customer leaves before checkout.
    talon_session_revoked
    • The state property is cancelled.
    • In the preceding request, the state property was closed.

    Example: The customer requests a refund.
  • When the Return cart items endpoint receives a request:

    Event nameTrigger criteria for the event
    talon_session_partially_returnedThe state property is closed.

    Example: The customer returns some of the items and expects the corresponding refund.
  • The Update customer profile endpoint receives a request with runRuleEngine=true:

    Event name
    (Rule Builder event type)
    Trigger criteria for the event
    talon_profile_created
    (Customer Profile Registration)
    The request includes a new integration ID.
    talon_profile_updated
    (Customer Profile Update)
    The integration ID was sent to Talon.One in a previous request.
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.

Custom events

Custom events are created by you and are also tied to a customer session. They add their custom attributes to the session. 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:

  1. Open your Application.

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

  3. In Associated Entity, select Event.

  4. In Event type, select the type of your choice from the list, or type a new value.

  5. 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.

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

The event now contains an attribute. You can now use 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

Once 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 '{
"sessionId": "mysessionid",
"profileId": "myprofileid",
"type": "pageview",
"attributes": {
"url": "some value"
}
}' 'https://mycompany.europe-west1.talon.one/v1/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.