Events

One of the foundations of behavior-based communication, user actions (events) will help you organize audience segments and design relevant two-way messaging.

Infobip data platform lets you track two types of events: custom ones coming from your website, app, or some other system, and standard ones that happen when you communicate with customers inside our products: Moments, Conversations, and Answers.  

Custom Events

These events are customer activities that happen on other platforms. For instance, once you configure custom events, you can see what pages your customers have opened and how many times. This activity will be recorded and stored in the People module.

For a quick overview of the profile activities, click the Attributes, Tags & Events page tab inside a person`s profile.

Properties

Properties are optional, and they allow you to include additional information when defining an event. Here are some examples: 

You can select Text, True/False, Date, or Number as parameter types in the event properties.

Define

Before the events are sent, they have to be configured on the Create custom event page: type in the event name, event ID, event description, and event properties. The event ID will be used for tracking.

Track

There are three ways to track events: Web SDK, API, and Mobile SDK. In this section, you will find guidelines for all of them.

But first, go ahead and "practice." Go to the People module, and on the Events page click the Web SDK tab. Scroll to the bottom of the page to select an event and a person related to it. Send event.

The event will appear on that person`s profile page.

Web SDK

The Web SDK allows you to capture events from the front-end of your website.  To learn how to add the Web SDK code to your site and use it to track custom events, refer to the guidelines and the Web SDK section of docs.

Events API

API is generally considered a more secure approach when it comes to sending events to Infobip from any back-end system. For implementation details, refer to the guidelines and see the developers’ guide.

The following are the quick steps to set it all up:

1. Create a Public API Key by accessing the Developers page in the web interface.

2. To send events via API, please adhere to our API specification and use the following:

• {{personId}} - unique person identifier (email, pushRegId, phone)
• {{eventId}} - event ID from the Events page
• {{AppKey}} - API Key from the Developers page
• {{Your personal Base URL}} - base URL you can get after logging in

Apply the POST method:
 

POST /persons/{{personId}}/definitions/{{eventId}}/events
Host: {{your personal Base URL}}/peopleevents/1
Authorization: App {{AppKey}}
Accept: application/json
{
"properties": {
 "property_key": "property_value”,
}
} 

Unlike JS SDK, API lets you send events related to a person identifier that already exists on the People platform. If you send an event with a person identifier which does not exist in People, you will get an error.

Mobile SDK

Mobile SDK serves to capture events from the mobile app. It involves standard and custom events.

Standard events are enabled for all the Moments users who have Mobile SDK implemented in their mobile app, and you don’t need to perform any additional actions to be able to track these. Check out the Channel Events section to see the list of available mobile app events.  

Custom events are those that you have defined yourself and want to track via Mobile SDK. You can use custom events to track user activities. For example, send a custom event via Mobile SDK when the user adds items to a shopping cart, purchases an item, or finishes exact steps in an onboarding process.

Learn more about how to set up mobile events tracking on iOS, Android and Huawei SDKs, and React Native, Cordova, and Flutter plugins. 

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.
• To send an event without a property, send the JSON body with empty properties.

Template Events

We have provided a number of default event templates that can be used out of the box for tracking profile behavior and activity.

The templates come pre-populated with the properties needed for various events including items viewed, items purchased, items being added to shopping cart, and more. 

To see available events templates in the web interface click Events > Template Events in the People module.

Standard Events

Events generated when your customers interact with the services provided by Infobip are called standard events. They are available in all events-related features within Infobip solutions.

Standard events include the following: 

• People Events
• Channel Events
• Product Events

Enable

Select the events that you want to track, and they will become available for use with the Infobip products that you have:

1. Go to the People page on the Infobip web interface.

2. Click People Events.

3. Navigate to the event category (People, Channel, or Product events), and select the check box next to the event you want to track and activate it. 

People Events

Create messages based on customer profile updates. These updates involve changes in Person Activity, Standard Attributes, and Custom Attributes.

Person Activity 

Track person activity through your site and create events based on user sessions and page view activity.  You can create events for the following activities which you need to activate in the Events area of People:

• Session Started
• Page View
• Person Merge
• Session Ended

By using a combination of the events you can create powerful scenarios such as: 

• Track anonymous visitor website visits. Follow the customers journey from being an anonymous visitor through to lead and customer conversion. 
• Targeted offering. If a person visits a 'mortgage' page 5 times during one month, send them an email and offer advice.
• Promo code for a specific category. When someone checks out the 'shoe category' page 3 times during one week, send a message with a promo code for shoes.
• Reactivation. Start a reactivation campaign and include those who haven`t visited your webpage in the last 45 days.
• Abandoned cart. Send communication after a person visits the 'search ticket' page and then the 'select ticket' page, but not the 'checkout page.'
• Survey for active customers. If someone has over 100 page views in 30 days, send them a survey.

Person activity events can be added to your site using a Javascript-based Web SDK that you can add to your website to track person activity. See Web SDK to learn more. 

Session Started - logs when a person visits a website.

Each session started event will contain the following properties automatically filled by the Web SDK

Page View - engage people based on their web page visits. 

Each page view event will contain the following properties that will be filled automatically by the Web SDK:

Session Ended - logs when a person stops being active on a website. 

Each session ended event will contain the following properties automatically filled  by the Web SDK

Person Merge - get information when person profiles have been merged.

Standard Attributes

Activity related to standard customer attributes that you can choose to track:

• Name changes
• Location changes
• Other changes such as date of birth or gender identification
• Tag changes
• Contact information

Contact Information

The push destination events provide information about the user activities involving mobile apps, and they are visible in people profiles on our data platform. They are generated via Mobile SDK. 

The following are the events that can be found within a person`s profile:

Custom Attributes 

These attributes cover more specific data related to your customers and their interests to help you reach out in an informed manner. They should be defined on the Configuration page in the People module. After you finish the configuration, go to the Events page and select the check box next to that custom attribute.

Channel Events

All channels that currently work with this feature have a set of events that you can choose from when you want to track the status of your messages and how customers react to them. 

By default, all channel events are active in the system so you don't need to make any changes during configuration.

Take a look below to see events by channel:   

Product Events

Events that belong to a specific Infobip product are called Product Events:

• In Moments, the product events will show when a person entered or exited a specific communication campaign. This event happens based on customer attributes and activity, and, most of all, in accordance with your settings.  
• In Forms,  we track the Submit Form event if the Processing Rules have been enabled for the specific form. This information can then be used to send the requested information to the form submitter.   

Events in Audience Segmentation

On the Segments page in People, events will help you create specific audience segments and organize the communication accordingly whether you want to send a message based on this event, check how many times a customer called your contact center, or something else. When creating segments, combine events and attributes for even more relevant segmentation. 

The selected customer attribute in the example below  is "country" and event is "tag added":

Events in Moments

In Moments, you can trigger a campaign based on custom events that you have defined previously or go for the predefined, standard events.

For example, start creating your communication flow and use the People-Real Time event trigger. Your custom "trigger event" could be Item Added to Cart. Add a communication channel and send a message to people who perform that action.

If you want to use events later on in the communication flow, the following elements will help you do it: Wait for an Event and Segment Audience.

 4. Specify the next step. For example, select the Wait for an Event element and then Checkout Finished as the event you will be waiting for. Enter the amount of time you want to wait for this action to happen.

Event Operators

When adding the Wait for an Event element, include an operator that will show if the event happened. 

Happened means that as soon as an event happens to a person, the communication trigger will be activated. You can also set the time and number of occurrences. For example, if you would like to trigger your flow and send communication every 5th time some event happens within a 7-day timeframe, you would specify the time as “within the last 7 days” and a number of occurrences as “equals 5 times.”

Use Not happened as a way to confirm that an event has not happened for the user. For example, if the user has not launched an App after a certain period of time.

Not happened should always be used with the happened condition. This is because we only ever know who an event occurs for. It does not give an indication of who the event did not occur for. If you create a block with two conditions 'happened for event 1' and 'not happened for event 2', then you can check which people had event 1 and also did not have event 2 at the same time. 

Various events and their operators can be combined within the same element, as shown below.

If a person has already fulfilled the conditions that you are including in the flow, that person will not enter the flow, at least not at this point. However, if the flow is recurrent, that same person could enter the communication later if they happen to match the set criteria sometime in the future.

​​​If you are still wondering what engagement strategy would be the best fit for your company, browse through the use cases.

Events in People Analytics

Events Segmentation and Funnel Analytics both offer the possibility to use standard events. In the People module, select, for example, Funnel Analytics, and from the drop-down list select the standard event you would like to use.

The events you choose will be used as a step in a funnel. If you opt for Events Segmentation, standard events will let you create a specific segment of the audience that you want to analyze. 

 

Events in External Systems

If you would like to use your events data in external systems, you can use People API to export events as compressed files to your Amazon Web Services (AWS) S3 bucket. 

Use Events Export API to:

• Submit an export event request (Post)
• Check the status of your export request (Get)
• Asynchronous cancellation of an export request (Del)
• Get a list of event definitions (Get)

Events Export Data Format

There are a number of data and file format considerations to be made when you submit an export event request to export events to an AWS S3 bucket.

The following information assumes you have already configured your AWS S3 bucket. If you have not yet done so, check out Amazon AWS documentation on how to set up an AWS S3 bucket.

Set up S3 bucket permissions

Once you have set up your S3 bucket, use AWS Identity and Access Management (IAM) to create a role that will be used by the Events Export application to access the S3 bucket.

The role requires two policies:

1. S3 access policy to allow access to your S3 bucket.
2. Trust policy to allow the Events Export application user to obtain a temporary session using the AWS Security Token Service. This code can be retrieved from the Events Export page of the Infobip web interface.

After you have set the appropriate permissions, your S3 bucket will be ready to accept exported files from Infobip.

Export files

Submit an export event request following the schema defined on Submit an export event request.   

After the request is complete files, containing events, are exported to a designated S3 bucket. You can specify the directory path, where the files will be saved within that specific directory of the S3 bucket.

Each file is compressed to gzip format. Filename format is <requestid>-events-<starttime(yyyymmddhhmmsssss)>-<endtime(yyyymmddhhmmsssss)>.json.gz</endtime(yyyymmddhhmmsssss)></starttime(yyyymmddhhmmsssss)></requestid>.

Once uncompressed, the file contains a maximum of 50000 rows. Each row contains exactly 1 event in JSON format.

Event schema

Each event has mandatory fields that are always present regardless of the event type and additional fields that are specific to the event type.

Mandatory fields

Event specific fields

Each event might have one or more additional properties that vary from one event type(definition) to another and carry additional information about the activity.

You can see the properties of any standard People event by adding the event definition ID to the following base URL: https://portal.infobip.com/people/events/definitions/. For example,  enter https://portal.infobip.com/people/events/definitions/emailLinkClicked to see the list of properties of the standard Email Link Clicked event.

You can enrich messaging events (e.g. Email Delivered) related to Moments campaigns with additional information about the campaign and messaging flow element:

To enable this functionality, set the enrichWithMomentsInfo parameter to True when submitting an export event request.