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: They are provided by Talon.One and are tied to a customer session. They are sent in every response from the Update customer session endpoint and include the following events:

    • talon_session_created
    • talon_session_updated
    • talon_session_closed
    • talon_session_cancelled
    • talon_session_revoked

    They can also be tied to a customer profile when you call the Update customer profile endpoint with runRuleEngine=true. The response can contain the following events:

    • talon_profile_created
    • talon_profile_updated
    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: They 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.

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 > Dev 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

    If you want 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://developerdocs.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.