Events
An event is an activity that an end user performs when interacting with your brand.
Example:
- Opening a link in your email
- Adding an item to a cart in your app
- Updating their phone number in a form on your website.
When an end user performs an action, the information about the action is saved as an event in People.
Example: When an end user interacts with a link, you can save the following information in People.
- Type of action (click or open)
- Source of the action (webpage or app)
- Time when the action was performed
- Web page in which the link was clicked
You can then use this information in different ways. Example: Send messages to end users when an event happens or analyze how many end users visit your web.
To view events, go to the Attributes, Tags and Events tab on the end user's profile page.
How to use events
The following are some examples of how to use events.
- Use event data to follow up with end users. Example: When an end user abandons items in cart, the abandoned cart event is logged. Send a follow-up email asking if they need help.
- Understand end user behavior patterns by analyzing event data.
- Use event data to recommend related products to end users. Example: If an end user purchases a mobile phone, the event item purchased is logged. Recommend accessories such as power banks and earphones.
- Use event data to segment audience. Example: Send a follow-up email only to end users who view a specific product on your website.
- Use events to personalize messages to end users.
- Use events in computed attributes. You can make calculations against event data in event aggregates and evaluate profiles when doing profile scoring.
Types of events
Events are of the following types.
-
Custom events: These are the events that you create in People to track end user activity on your digital assets such as your websites, mobile apps, and other platforms and applications. Custom events are specific to your business.
-
Template events: Event templates that are pre-populated with event properties, which you can customize and use for common use cases, such as e-commerce.
-
Standard events: Predefined events that occur when the following happen.
- You communicate with end users through Infobip products, such as Moments, Conversations, and Answers.
- When person profiles (attributes, destinations, or tags) are updated.
Standard events include People events, Channel events, and Product events.
Custom Events
These are the events that you create in People to track end user activity on your digital assets such as your websites, mobile apps, and other platforms and applications. Custom events are specific to your business.
Create a custom event
-
On the Infobip web interface (opens in a new tab), go to People > Events > Custom events tab.
-
Select Create event.
-
In the Event name field, enter the name of the event. Example: AddedToCart.
-
Make sure that the Event ID is unique. This field is automatically populated based on the event name. This ID is used to track the event by using the Infobip API and SDKs.
-
(Optional) In the Description field, enter the description of the event.
-
(Optional) Create as many properties as required.
To add a property to an event, do the following.
-
Select Add event property.
-
In the Name field, specify the name of the property.
-
In the Type field, select the data type of the property.
For more information about properties, refer to the Event properties documentation.
-
Event properties
Event properties enable you to add additional information to an event.
Example: For the event adding a product to cart, you can create the following properties.
Property | Description |
addedCart | Successful addition of the product to cart |
productID | Unique identifier of the product |
productName | Name of the producte |
productPrice | Price of the product |
Data types for properties
Event properties can have the following data types.
Data type | Description |
Text | Use for properties that are in text format. Example: productName and productDescription. |
Text | Use for properties that contain one of only two values - True or False. |
Date | Use for properties that contain date values. |
Number | Use for properties that are in a number format. Example: productPrice |
List | Add a list as a property. Example: To pass information about an end user's shopping cart from your website to a flow in Moments, create a cartItems property of type List. In this property, add fields, such as item name, item ID, quantity, and price. You can add a maximum of 1 List property to an event. You can add a maximum of 128 fields to a List property. |
Examples of properties
The following table shows examples of properties.
Event | Properties |
Item Added to Cart | Item Name Item Price |
Form Filled Out | Fields Filled |
Flight Tickets Purchased | Travel Type |
Support Ticket Closed | Ticket Id Closure Date |
Test send an event
-
On the Infobip web interface (opens in a new tab), go to People > Events > Web SDK tab.
-
In the Try it out section, select an event and a person profile related to it.
-
Select Send event.
The event is added to the person's profile page.
Currently, you cannot set values for list properties in test events.
Track custom events on your platform
You can track custom events through the following.
- Web SDK
- API
- Mobile SDK
Web SDK
The Web SDK enables you to capture events from your website. To learn how to add the Web SDK code to your website and use it to track custom events, refer to the guidelines and the Web SDK documentation.
Events API
API is considered a secure way to send events to Infobip from other systems.
When you use API, you can send events only for person identifiers that already exist in People. If you send an event for a person identifier that does not exist in People, you get an error.
For details about the implementation, refer to the guidelines and the developer guide (opens in a new tab).
Mobile SDK
Use the mobile SDK to capture events from mobile apps.
You can capture the following types of events.
-
Standard app events are enabled for all Moments users who have Mobile SDK implemented in their mobile app. You do not need to perform any additional actions to track these events. Example: application installed.
Refer to the Channel Events section to see the list of available mobile app events.
-
Custom events are the events that you create and configure, to track end user activities. You can track custom events by using Mobile SDK. Example: send a custom event by using Mobile SDK when an end user adds items to a shopping cart, purchases an item, or finishes the steps in an onboarding process.
Learn about how to set up mobile events tracking on the following.
- iOS (opens in a new tab)
- Android and Huawei (opens in a new tab) SDKs
- React Native (opens in a new tab) plugin
- Cordova (opens in a new tab) plugin
- Flutter (opens in a new tab) plugin
Mobile SDK does not support tracking list poperties in events. For more information, contact your Infobip account manager.
Guidelines
When a custom event is sent through a call to the Web SDK or Events API, there must be a 1:1 mapping between the event and the event schema.
The following guidelines apply.
- If a call contains more properties than defined in the schema, the call is rejected.
- If a call contains fewer properties than defined in the schema, the properties that are not included in the call have a value of NULL in the event.
- If a call contains properties that do not match the schema, the call is rejected. Example: The property in the event schema is in uppercase but the property in the event call is in lowercase.
- If the property value is a string, add it within quotation marks. If it is not, do not use quotation marks.
- Even if the event does not have properties, you must send the JSON body. In this case, send an empty JSON body. Example: {{}}
Template Events
Event templates are pre-populated with event properties, which you can customize and use for common use cases, such as e-commerce.
The templates contain both mandatory fields and optional properties.
The following table shows a list of template events. To see this list of events templates in the web interface, go to People > Events > Template events tab.
Template name | Purpose | Properties |
---|---|---|
itemViewed | This event shows the details of an item viewed by a profile. | itemID: Number. Mandatory duration: Number. Optional |
itemPurchased | This event shows the details of a purchase made by a profile. | itemID: Number. Mandatory amount: Number. Optional price: Number. Optional profit: Number. Optional |
ratingAdded | This event shows the rating that a profile gave to an item. | itemID: Number. Mandatory rating: Decimal. Optional |
addedToCart | This event shows details of an item that a profile added to a cart. | itemID: Number. Mandatory amount: Number. Optional price: Number. Optional |
addedToFavourites | This event indicates that a specific item was bookmarked by a profile | itemID: Number. Mandatory |
viewPortionSet | This event indicates partial view of an item, such as a video or article, by a profile in a session. | itemID: Number. Mandatory portion: Decimal. Optional* sessionID: String. Optional** * Portion indicates the viewed portion of an item. It is a numerical value between 0.0 (item not viewed) and 1.0 (viewed item fully). The viewed portion depends on the position at which the item was viewed. Example: If the end user opens a video at 50%, but only views 10% after that, then the portion is 0.1, and not 0.6. ** The ID of the session in which the end user viewed the item. The default value is null. |
Standard Events
Standard events are generated when end users interact with your services through Infobip products such as Moments, Conversations, and Answers.
These events are available in all elements that support events in these products. Example: In Moments, you can use events in elements such as triggers.
Enable or disable a standard event
To use events in Infobip products, you need to enable the events in People.
To enable or disable an event, do the following.
- On the Infobip web interface (opens in a new tab), go to People > Events.
- Go to the required event category (People events or Product events).
- To track an event, select the check box next to the event.
- To stop tracking an event, deselect the check box next to the event.
- To save the changes, select Activate.
Types of standard events
Standard events include the following:
People Events
People events are triggered when there are changes to a person profile. The changes could be one of the following.
- Person activity: Activity done by the end user. Example: logged in.
- Standard attributes: Changes to standard attributes.
- Custom attributes: Changes to custom attributes.
You can create personalized messages based on these profile updates.
Person activity
Use cases for Person activity events
- Track anonymous visitor website visits: Follow the end user's journey from being an anonymous visitor through to lead and conversion.
- Targeted offering: If a person visits your mortgage page 5 times in a month, send them an email about mortgage offers and advice.
- Promotional code for a specific category: When an end user looks at the Shoes page 3 times within a week, send them a message with a promotional code for shoes.
- Reactivation: Start a reactivation campaign that includes end users who have not visited your webpage in the last 45 days.
- Abandoned cart: Send a communication after an end user visits your Search tickets page, then goes to the Select ticket page, but does not go to the Checkout page.
- Survey for active customers: If an end user has more than 100 page views in 30 days, send them a survey.
Track Person activity events on your website
To track Person activity events on your website, add a JavaScript-based Web SDK to your website. See Web SDK for more information.
Types of Person activity events
- Session started
- Page view
- Session ended
- Person created
- Person merged
Session started
This event logs when an end user visits your website.
Each Session started event contains the following properties that are automatically filled by the Web SDK.
Property | Description |
---|---|
Session ID | Unique session identifier |
Session start | Time when the session started. Format is DD/MM/YYYY HH:MM:ss |
Session type | Web |
UTM parameters | utm_source utm_medium utm_campaign utm_term utm_content If the Session type is Web and no UTM tags are set in the page request, then utm_source is set to direct. |
Page view
This event logs when an end user views your web page. Use this event to engage end users based on these views. Example: If an end user views your Shoes page 3 times in a week, send them a message with a promotional code for shoes.
Each Page view event contains the following properties that are automatically filled by the Web SDK.
Property | Type | Description |
---|---|---|
pageTitle | String | The title of the current page. |
url | String | The URL of the page that was loaded for the PageView. This property value can have a maximum of 1,500 characters. If the URL exceeds this limit, the property value is truncated to 1,500 characters. |
domain | String | The domain portion of the request URL. |
path | String | The path portion of the URL. This value should start with the slash (/) character. |
deviceType | String | The type of device that is used to load the page: This property can have the following values. unknown mobile tablet desktop spider TV console |
timestamp | DateTime | Time (date, hour, minute, second) when the interaction occurred. |
browserName | String | The browser name, such as Chrome or Firefox This information is obtained from the User-Agent header of an HTTP request. |
browserVersion | String | The reported software version of the browser. This information is obtained from the User-Agent header of an HTTP request. |
browserOS | String | The reported operating system that the browser is running on. Example: Windows or Linux. This information is obtained from the User-Agent header of an HTTP request. |
referrer | String | The Referrer HTTP request header contains an absolute or partial address of the page making the request. |
browserLanguage | String | Browser language. |
websiteLanguage | String | Website language. |
Session ended
This event logs when an end user stops being active on a website.
Each session ended event contains the following properties that are automatically filled by the Web SDK.
Property | Description |
---|---|
Session ID | Unique session identifier |
Session End | Time when the session ended. Format is DD/MM/YYYY HH:MM:ss |
Session Length | Session End - Session Start. In seconds. |
Session Type | Web |
UTM parameters | utm_source utm_medium utm_campaign utm_term utm_content If the Session type is Web and no UTM tags are set in the page request, then utm_source is set to direct. |
Person created
This event logs when a person profile is created.
Person Merged
This event logs when person profiles are merged.
Standard Attributes
Track changes to standard attributes in profiles.
You can track the following standard attributes.
- Name changes in person profile: Changes to a person's first, middle, and last names.
- Location changes in person profile: Changes to address, city, and country.
- Other changes in person profile: Example: Date of birth.
- Tag changes: Tag is added or removed from a profile.
- Contact information: Addition or removal of channels over which the person can be contacted.
Contact Information
The following contact information events are available in a person profile.
Contact Information Type | Events |
---|---|
Email address added Email address changed Email address deleted | |
Push | Push contact added Push contact changed Push contact deleted These push destination events provide information about the end user's activities on mobile apps. These events are generated by Mobile SDK and are displayed in person profiles in People. |
Facebook contact added Facebook contact changed Facebook contact deleted | |
SMS/Voice/MMS | Phone number added Phone number changed Phone number deleted |
Other contact information | Contact information changed |
Custom Attributes
Track changes to custom attributes in profiles.
To minimize cluttering the user interface in People, avoid including attributes (opens in a new tab) that you do not plan to use.
Channel Events
These events are specific to the channel that is used to communicate with the end user. Use channel events to track the status of your messages and how customers react to them.
By default, all channel events are active. So, you do not need to make any changes during configuration.
The following table shows the events that are supported by the channels.
Channel | Event name |
---|---|
Sent Delivered Opened Clicked Unsubscribed Complained | |
Mobile push | Sent Delivered Opened |
In-app message | Sent Delivered Seen |
SMS | Sent Delivered Clicked |
Sent Delivered Opened Clicked | |
Viber | Sent Delivered Opened Clicked |
Messenger | Sent Delivered Opened Clicked |
Mobile App | Personalize Depersonalize Install Uninstall App Launch |
Voice | Voice Call Initiated Voice Call Answered Voice Call Not Answered Voice Busy Voice Call Answered By Machine Voice Inbound Call Answered Call Forwarded Busy Call Forwarded Not Answered Voice IVR Played Voice IVR Information collected Voice User Hang Up |
LINE | Sent Link Clicked |
MMS | Sent Delivered |
Product Events
These events are for specific Infobip products.
- Moments: The product events show when a person entered or exited a specific communication campaign. This event happens based on customer attributes and activity, and in accordance with your settings.
- Answers: The product events show when an end user started or ended a specific chatbot session, and if the session failed to start. These events are created only if a Person profile exists in People for the end user.
- Conversations: The product events show when an end user created or closed a conversation. These events are created only if a Person profile exists in People for the end user.
- Forms: You can track the Submit Form event if the processing rules (opens in a new tab) are enabled for the form. You can then use this information to send the requested information to the form submitter.
Use events to personalize messages
The following is an example of how to use an event from your app to personalize messages to end users.
- In People, either identify an existing event that you want to use or create a custom event.
- Integrate the event in your app. The app can now send the event to the Infobip platform.
- In Moments, create a flow that is triggered by the event.
- Map the data in the event to flow variables.
- Use the flow variable to personalize the message to the end user.
Use events to segment your audience
Use events to create audience segments based on end user behavior. You can then organize your communication based on the segments. Example: You can decide whether to send a message based on the event or check the number of times an end user called your contact center.
You can create segments on the Segments page in People. When creating segments, combine events and attributes for more relevant segmentation.
Currently, segmentation for the event property of type List is not supported.
In the following example, the selected attribute is Country and the event is Tag added.
Use events in Moments
In Moments, you can use events in the People real-time event trigger and the Wait for event element.
To track standard events, you must enable the events in People.
Currently, segmentation for the event property of type List is not supported.
People real-time event trigger
Trigger a flow campaign based on custom events that you have defined previously in People, or based on predefined (standard) events.
Example: To send a message to all end users who add items to cart, in your communication flow, use the People real-time event trigger with the custom event Item Added to Cart.
Wait for event element
If you want to use events at a later stage of the communication flow, use the Wait for event element.
Example: In the Wait for event element, select Checkout Finished as the event to wait for. Enter the amount of time for which the element needs to wait for this event to occur.
Use events in People analytics
Use events in the following.
- Events Segmentation: Use events to create the audience segment that you want to analyze.
- Funnel Analytics: Select an event to use as a step in a funnel.
Example: Select Funnel analytics, and then select the standard events that you want to use.
Use events in external systems
To use events data in external systems, use the People API (opens in a new tab) to export the events as compressed files to your Amazon Web Services (AWS) S3 bucket.
Use Events Export API (opens in a new tab) to do the following.
- Submit an export event request (opens in a new tab) (Post)
- Check the status of your export request (opens in a new tab) (Get)
- Asynchronous cancellation of an export request (opens in a new tab) (Del)
- Get a list of event definitions (opens in a new tab) (Get)
Process
Set up AWS S3 bucket
Refer to the Amazon AWS documentation (opens in a new tab) to learn how to set up an AWS S3 bucket.
Set up S3 bucket permissions
Use AWS Identity and Access Management (IAM) to create a role that is used by the Events Export application to access the S3 bucket.
The role requires the following policies:
- S3 access policy to allow access to your S3 bucket.
- Trust policy to allow the Events Export application user to obtain a temporary session using the AWS Security Token Service. You can retrieve this code from the Events Export (opens in a new tab) page of the Infobip web interface.
After you set the required permissions, your S3 bucket is ready to accept exported files from Infobip.
Export the events
Submit an export event request following the schema defined on Submit an export event request (opens in a new tab).
After the request is complete, files containing events are exported to a designated S3 bucket. You can specify the directory path of the S3 bucket in which to save the files.
Each file is compressed to .gzip format. Filename format is
<requestid>-events-<starttime(yyyymmddhhmmsssss)>-<endtime(yyyymmddhhmmsssss)>.json.gz</endtime(yyyymmddhhmmsssss)></starttime(yyyymmddhhmmsssss)></requestid>.
When the file is uncompressed, it contains a maximum of 50,000 rows. Each row contains 1 event in JSON format.
Event schema
Each event has the following fields.
- Mandatory fields that present in all events.
- Additional properties that are specific to each event.
Mandatory fields
Field name | Value format | Example | Notes |
---|---|---|---|
definitionId | String | personEnteredFlow | Definition(type) of the event. See Get list of event definitions (opens in a new tab) endpoint. |
eventId | String | fent_100000000270199_1_1647967373262 | Unique ID of the event. |
sessionId | String | 61bc52b9ba3ae43407dbb246 | Unique ID of the web session for events that are tracked by using People Web SDK In all other cases, this value is NULL. |
personId | String | 2342 | Unique internal ID of the profile for which the event is registered. |
externalPersonId | String | CS26_342 | External ID of the profile for which the event is registered. If the profile does not exist, this value is NULL. |
occuredTime | String | 2022-09-14T15:00:35.495+0000 | Timestamp of when the system receives the event, in ISO-8601 format. |
Event specific fields
Each event might have one or more properties that contain additional information about the activity. The properties vary from one event type to another.
To view the properties of a standard event, add the event ID to the following base URL: https://portal.infobip.com/people/events/definitions/ (opens in a new tab).
Example: Enter https://portal.infobip.com/people/events/definitions/emailLinkClicked (opens in a new tab) to see the list of properties of the standard event, Email Link Clicked.
For a list of available event IDs for the account, use Get list of event definitions (opens in a new tab)
If a property name in a custom event is the same as the name of a mandatory field, in the export file the property name is prefixed with the event ID.
Example: For a custom event, a property is externalPersonId. But externalPersonId is the name of a mandatory field. So, in the export file, the property name is prefixed with the event ID, myCustomDefinitionID. The property name in the file is now myCustomDefinitionID_externalPersonId.
Events export can provide additional properties for events produced by Moments. Example: campaignName. You can export this information and use in external systems. The following table shows a list of these properties.
Field name | Value format | Example | Notes |
---|---|---|---|
campaignName | String | Communication name 56 | The name of the campaign, if this data exists |
elementName | String | Send email | The name of the flow element, if this data exists |
campaignStart | String | 2022-06-14T10:54:30.033+0000 | The start date and time of the campaign, if this data exists |
flowElementId | String | 10000005271386-12 | The ID of the flow element, if this data exists |
To enable this functionality, set the enrichWithMomentsInfo parameter to True when submitting an export event request (opens in a new tab).