The Custom events module offers a solution to register and reward customer actions that are not provided by Antavo’s built-in functionalities. You can define your own events in the Custom events module configuration page and send these events through our Events API. You can also use the module to expand built-in events with additional fields.

Find the configuration page of the Custom events module by typing ‘custom events’ into the search bar of the Modules menu. The page will open to the list of built-in events that have been updated or extended with custom attributes and custom events that have been added with the following information:

• Name of the event

• Unique ID of the event

• Built-in

  • yes - the event is a built-in event provided by default

  • no - custom event configured through this module
    
    

Open

Defining a new event

• Click the ‘Create new custom event’ button in the sidebar

• Add the unique ID of the event
  The machine-readable ID of the event that needs to be referenced when sending API calls.

• Add a label
  The listing name of the event across the interface of the Backoffice, including workflows and customers' event streams.

• Add a description
  The description serves informative purposes in the Backoffice, reminding the user what the event is used for.

• Assign a default point value to the event
  The number of points you add here will be awarded to the customer when the event is registered on their account. You can use the Workflows module to override this on certain conditions.

• Enable ‘One-time' option if the event should only be registered once in the customer’s lifetime
  Every further attempt will fail and the Events API will respond with an error.

• Decide if the event should be added to the response that the Display API returns when sending a request for the list of customers' events.

• Select the account to which this event should be recorded
  This setting applies if the account is not specified in the event that is sent through the Events API or added manually in the Backoffice.

• Click ‘Save’

Open

Adding a new custom attribute

Add custom attributes to expand events with data fields (eg. if you want to add the store location or the name of the cashier to the Checkout event).

Click the ‘Edit’ button next to the event that you’d like to extend and navigate to the Attributes tab.
First, you’ll find the list of attributes that have already been added to the event with the following information:

• Name of the attribute

• Unique ID of the attribute

• Data type

• Required

  • yes - the event cannot be registered without a valid value defined in this attribute

  • no - the event can be registered without including this attribute

• Built-in

  • yes - the event is a built-in event provided by default

  • no - custom event configured through this module

• Tags associated

Configure an attribute

• Click the ‘Create a new attribute’ option in the sidebar

• Add a label
  The listing name of the attribute across the interface of the Backoffice, including workflows and customers' event streams.

• Define the unique ID
  The machine-readable ID of the attribute that needs to be referenced when sending API calls.

• Add a description
  The description serves informative purposes in the Backoffice, reminding the user what the attribute is used for.

• Select the field type
  Select the type of data that is stored in the attribute. When sending the data through API, please make sure that it is sent in the format required by the selected type, otherwise, the API request will fail.

  • String

  • Numeric

  • Boolean

  • Select
    Add the selectable options by defining possible values.

  • URL

  • Date

  • Datetime

  • Multiple choice
    Add the selectable options by defining possible values.

  • List

• Add a default value (only applicable for String, Numeric, Boolean and Url type attributes)
  You can enter a default value for event fields.
  After the new event attribute is saved, the default value will be automatically populated in all the events that will be registered moving forward if no value is provided in the API request.
  Please note, that as events are WORM (Write Once-Read Many) objects, the field values cannot be populated with any default value that was configured after the event has been registered.

• Format (only applicable for String and List types of fields)
  The format of String and List types of values can be further specified to Date, URL, Email, Phone number formats, the API will validate the values accordingly.

• Tags
  Tags define the ways how attributes can be accessed and managed in the system.

  • API - the field is included in the response returned by the History endpoint of the Display API

  • searchable - the value of the field can be used as a search condition when requesting customer data through the Display API

  • importable - the value of the field can be populated through the Imports module
    Please note, that as events are WORM (Write Once-Read Many) objects, the field values cannot be modified after the event has been registered.

  • groupable - the data values of the field can be grouped together when configuring charts to be displayed on the Dashboard

  • filterable - the field can be used as a filter condition when requesting customer data through the Display API, find further information about filtering here

  • unique - the same field value can only be registered once, the value cannot be saved to the same field of any other customer

• Access Level
  Select the access level that should apply to the event field. Users without the defined level of access cannot add and/or view this attribute through the Events tab of Customer Insights.
  Read more about access levels here.

Data and privacy controls

• Required
  Is this attribute critical or supplementary to the custom event? If an attribute is required but not included in the event that is sent through the API, the API request will fail and the event will not be registered in Antavo’s database.

• Computed
  The value of computed fields cannot be defined when registering the event under Customer Insights or through the Events API.

• Save to customer
  If enabled, this will save the attribute to the customer object.

Don’t forget to click ‘Save’ at the bottom of the page.

Extending a factory action

There is an option to extend built-in events with custom attributes manually.

• Click the 'Extend factory action' option in the sidebar

• Select the event from the dropdown menu

• Click ‘Extend’
  This opens up the editor interface of the event.

• Update event settings (if necessary) and click ‘Save’

• Navigate to the Attributes tab

• Add new attributes as described above

Managing events and attributes

Edit an event or an attribute

On the list pages, click the ‘Edit' button next to the event or attribute that you’d like to edit. After you have updated the settings, make sure you click ‘Save’ before leaving the page.

Delete an event

You can delete custom events by clicking the ‘Archive’ button on the right corner of the event editor interface.

Restore an event

You can unarchive an archived event, but clicking the ‘Extend factory action’ in the sidebar and selecting the name of the archived event. Click ‘Extend’ and then the ‘Unarchive’ button in the right corner of the event editor interface.

Delete an attribute

Event attributes cannot be deleted. If you stop using an attribute, make sure the ‘Required’ checkbox on the editor interface is empty.

Translate events and attributes

The labels and descriptions of events and attributes are translatable on the configuration interfaces so that the event history can be provided in multiple languages. Click the blue ‘Translate’ button next to the field to add translations.

Best practices

• When rewarding custom actions with points, you can specify certain conditions for the activity by using Workflows or the Challenges module. The Challenges module provides out-of-box functionalities to configure the maximum number of completions, repeat intervals, availability for specific segments, as well as start and end dates.

• If you use the Challenge module, please make sure that the number of points to be awarded for this challenge should be set in the Challenges editor, and the point value of the event must be set to 0 on the event editor interface, to prevent double rewarding.

• Frequent examples of custom events:

  • Using the search bar

  • Adding an item to a wishlist

  • Adding an item to favorites

  • Subscribing to newsletter

• You can even define actions with negative points. A common use case for point deduction is a newsletter unsubscription event.