Working with Events#
This document introduces the high level workings of the mechanisms behind the Antavo loyalty program. Antavo has been built with flexibility and robustness in mind and reading through this guide provides an overview of Events, a key Antavo concept, well as the concepts of integration.
Events#
Events are clearly structured, versatile containers which can be used to store customer data including interaction history enhanced with relevant contextual metadata. These can be used to see your audience’s interactions in various different channels, online, mobile or in-store.
Events are micro documents that represent customers’ actions and contain metadata details on the location, method and time of the interaction. Typical interactions considered to be events include a customer purchases in a retail store; an online shop event; engagement with a newsletter and content sharing from a site. Antavo’s modules can also define and record customer events e.g., a customer claims a reward, earns points; their tier gets upgraded results in an event written to the customer.
Event definition can be completely customized to suit your business requirements and new events, specific to your business needs, can be easily introduced into the system.
Antavo comes with predefined “factory” events to facilitate a smooth and easy integration of Antavo with pre-existing business processes. The factory events contain all the predefined relevant metadata and they work out of the box with Antavo core components and modules work. These events enable the quick and easy tracking of basic interactions e.g., daily logins, purchases made on various channels, social activities with ease.
Your ecosystem can be further expanded with relevant, bespoke events, e.g., an interaction with the lookbook in your mobile application or someone plays a website minigame website.
There is no limit to the number of events which can be recorded. Events are write once read many (WORM) objects and once created, cannot be removed, altered or reassigned to different customers. Events are permanently stored until a customer opts out from the scheme/system.
Antavo does not expose any API methods or other interfaces to remove events. This is an important and conscious decision as it maintains the integrity of data on which solutions are built. However, depending on the type of events, there are multiple means to negate their effect on the customer’s point balance or tier.
The events related to the lifecycle of an order should be managed with the respective order lifecycle events.
For example, Antavo offers an event called checkout_update which updates the list of items a customer purchased in a particular checkout, adding/removing items, changing quantities or manipulating the total value of the purchase.
checkout_reject events can be created for the scenario in which customers return their whole purchase.
The effect of other events can be remedied by manually adding/deducting points from the customer’s account or administering events using the Loyalty Platform. These tasks can be easily performed by a customer service team or automatically using API interfaces. In the unlikely scenario that these solutions do not resolve any issues, Antavo client support would be able to assist.
Antavo can process and store events coming from various different input sources:
API: The Events API is the primary interface for registering events
Import: Large numbers of events can be simply imported using Events Importer by combining the events into a CSV file. This can also be used for events generated by third-parties systems where integration using the Antavo APIs is not feasible
Direct Integrations: Antavo can integrate with CRM systems, marketing clouds and platform tools, e.g., Segment, to enable loyalty data flow between different client systems. These integrations can also create events in Antavo e.g., when a lead becomes a customer, a customer opens a newsletter, or a visitor browses through a website
Internal: Antavo core components and modules also generate events as part of their operations
API interactions#
A great example of how the Antavo API system works in recording an event is a customer purchase scenario. This can be done by calling in a checkout event. This is a nested JSON file which contains the attributes of the purchase and attributes of the purchased items.
{
"customer": "374397439743",
"action": "checkout",
"data" : {
"total": "200",
"transaction_id": "5475-4343-4343-4343-3333",
"items" : [
{
"transaction_id": "5475-4343-4343-4343-3333",
"product_id": "TUFA-8888-94394-EN/XL/YELLOW",
"product_name": "Yellow T-Shirt",
"product_url": "https://example.com/yellow-t-shirt",
"quantity": "1",
"subtotal": "200",
"price": "200",
"product_category": "t-shirts"
}
]
}
}
The customer attribute denotes the unique customer ID.
This should be identical in every scenario in which purchases are called for the same customer, regardless of the channel of purchase.
This can be easily achieved if purchases are called in from a ERP or Order Management System, or if a unique loyalty identifier is assigned for every customer.
The top-level action attribute should specify the action performed by the customer and depending on the type of action, additional attributes can be specified using the data Key .
The above event can be called in in a development environment the Events API using cURL:
curl -X POST \\
'https://api.<API_REGION>.antavo.com/events?api_key=<API_KEY>' \\
-H 'Content-Type: application/x-www-form-urlencoded' \\
-H 'cache-control: no-cache' \\
-d
'customer=374397439743&action=checkout&data%5Btransaction_id%5D=5475-4343-4343-4343-3333&data%5Btotal%5D=200&data%5Bitems%5D%5B0%5D%5Btransaction_id%5D=5475-4343-4343-4343-3333&data%5Bitems%5D%5B0%5D%5Bquantity%5D=1&data%5Bitems%5D%5B0%5D%5Bprice%5D=200&data%5Bitems%5D%5B0%5D%5Bsubtotal%5D=200&data%5Bitems%5D%5B0%5D%5Bproduct_name%5D=Yellow%20T-Shirt&data%5Bitems%5D%5B0%5D%5Bproduct_id%5D=TUFA-8888-94394-EN%2FXL%2FYELLOW&data%5Bitems%5D%5B0%5D%5Bproduct_url%5D=https%3A%2F%2Fexample.com%2Fyellow-t-shirt&data%5Bitems%5D%5B0%5D%5Bproduct_category%5D=t-shirts'
The redacted profile of the customer involved in this event should be received, as a JSON object, in the response. Some additional attributes of the recorded events might also be returned e.g., the recorded event’s ID, points earned. A similar request in a production system would have to be signed
The Events API documentation also contains additional information regarding error handling, request and response formats and generic usage principles.
Importing Events#
Antavo’s Import module is the most effective and efficient mechanism for large volume data migrations where APIs/webhook connections would be overloaded Events can be imported as CSV input file with each column corresponding to an event attribute. The uploaded document is processed asynchronously and the progress can be followed on the interface provided in the Backoffice. Previous input files can also be accessed. Further information is available in the Imports module user manual
_id,action,email,first_name,last_name
374397439743,opt_in,demo-user@example.com,John,Example
345454656512,opt_in,demo-user@example.com,Bill,Overback
342856642764,opt_in,demo-user@example.com,Claudette,Moral
Internal Events#
Various different modules and internal components of the Antavo Enterprise Loyalty Cloud generate events, assigned to customers. .. e.g., if a customer has a birthday, a service automatically generates an event to allow event-based triggers to fire and starts different automation workflows. Automation workflows also write events to the customer.
Usage#
Antavo’s Loyalty Automation tool was designed and gives the ability to instantaneously fine-tune the customer engagement journey flows, from modifying the loyalty program mechanism to setting up periodic campaigns. Multiple automation workflows for each campaign can be set up in the Automation Tool.
A new automation workflow can be triggered by date, on a recurring basis or by an event. Event-based triggering unlocks the potential to limit and efficiently target the audience of the workflow based on the different attributes of the specific event. For example a workflow can be set up which runs each time a customer uses the mobile application and sends out a series of location-relevant offers depending on the last-known location of the customer.
The dedicated user manual. contains detailed information on how to use the Loyalty Automation tool and contains many different use cases and practical tips.
Series of events can also be interpreted as a stream and this can be used to visualize the whole history of the customer. This is useful when running a service desk or event history is needed for CRM tasks. Individual customer’s stream of events can be checked by opening up the corresponding profile in the Loyalty Platform and navigating to the Events History view.
Concepts and Restrictions#
The following section provides a deeper understanding of the workings of an Antavo event and is suitable for those wanting to integrate and use Antavo technologies to deliver advanced customer retention projects.
Inspecting events#
A loyalty-centric vision of customers’ data and recorded events is extremely important. During project implementation, data analysis can easily reveal defective business processes or badly implemented code whilst visualizing data during daily operations could reveal discrepancies and help cleanse them. Compliance with General Data Protection Regulations (GDPR) also requires an awareness of what data is recorded and assigned to a particular customer.
Navigating to a customer’s unified profile and selecting the Events History view enables the browsing through a paginated list of all events recorded for a customer. All data can be easily exported and externally processed, if desired. The export process can be initiated with selecting the events of interest and a few other filters and then requesting the export. Downloading will start as soon as the data is ready.
Default event properties#
An event always has the following common properties
Property |
Description |
|---|---|
action |
Event action label |
admin |
The name of the administrator user |
customer |
The unique Customer id |
date |
The event’s date |
name |
The name of the event |
points |
The points earned for the given event if running a points-based loyalty scheme. Can be negative to remove points. Default - 0 |
IP Address |
Shows the sender IP address for an event sent in through APIs. |
Source |
This shows the source of the event
|
Timestamp |
Time of event in ISODate format |
User-Agent |
APIs event Client-side events show the browser user agent, API clients, e.g., Postman, Insomnia, will show their respective user-agent footprint. Upload events Client-side user-agent |
unix_timestamp |
The time of event, recorded as unix timestamp |
Sensitive Information#
Antavo handles all event data transparently. All data submitted to Antavo in an event is viewable by anyone who has permission to access the customer profiles. Therefore, no payment information, credit card information or sensitive medical information should ever be sent as event attributes.
There is non-sensitive information which when linked to a specific customer becomes more sensitive. For example, general details and information regarding a product is generally considered as non-sensitive but should be considered private when combined with the contents of the customer’s cart. Sensitive/private information should be handled with care and should be secured in transit and at rest as well.
Antavo has implemented the follow protocols in order to maximize customer privacy:
Events that contain personally identifiable information (PII) or transactional details can only be called in using signed API requests
Some behavioral data can still be called in from the client-side but the client-side code has to access the API through secure connection (https)
The client’s responsibilities include
The management of API keys and API secrets
The provision and deprovision of Platform accounts with the appropriate roles
Management of administration roles