Events API
Events objects allow a third party to submit data representing non-purchase actions taken by a customer. For submitting purchase-based events like transactions, see the POS APIs. These actions are evaluated and acted upon based on the rules engine configuration for a specific campaign or outcome configured in the platform.
Some examples of customer-triggered events could include downloading an application, writing a product review, or responding to a survey.
Responses contain state data related to any completed behaviors completed in active campaigns. Events can be represented in the user timeline if an event template is configured to do so. For more details, the Timeline APIs.
Other actions might include:
- Triggering a message
- Receiving a reward
- Increasing a points balance
- Qualifying for a new tier value
- Showing a new campaign-specific state
- Displaying the status or progress of a campaign
Often customers are engaging with a variety of campaigns. As events are generated and managed, you might want to utilize some of the APIs under Campaigns grouping. These APIs provide several different methods, including some for learning about the completed and ongoing activities performed by customers.
Individual events can be understood as parts of an event history. You can access and manage these histories as timelines which are served by the Timeline APIs.
This API provides the following methods:
Before you begin working with one of the methods listed above, consider the conceptual information detailed in in the overview below.
Overview
Events handle real-time and background event processing that feeds into the platform's action logic. This can be understood in terms of the requests and responses that define the transactions.
Request Data
The SessionM Platform can process activity-based event requests via the Events API. Examples of basic activity events range from digital engagement with content, such as opening an app or clicking on a web form, to other simple activity events, such as abandoning a shopping cart within a mobile app or on an e-commerce site. It is generally associated with metadata such as a count for the number of times it has occurred and the date of occurrence. Note that purchase events are supported for legacy implementations only. For any new development, please use the Transactions API.
Response Data
All events submitted to the Events API are evaluated in real-time against campaigns associated with each event. When rule criteria is met based on the submission of the event, the API will respond with state information related to each associated rule.
Possible types of response data include:
- Actions
Event submission can also trigger simple or complex behaviors. A behavior is defined by the client in the platform using events and their attributes. During an event submission, the caller to the API may receive a list of behaviors that were completed because of the event. For example, an event may be associated to a simple behavior, such as the abandonment of a shopping cart. However things could be more complex, such as an action tracking the abandonment of a shopping cart for the 2nd time within a 24 hour period.
- Messages
Event submissions can also trigger messaging or notifications. For example, a campaign may be configured to deliver a notification when a consumer makes their 2nd purchase within a 30-day period.
- Batch Process User Events
In some instances, a client cannot or does not wish to support real-time submission of events. In these cases, this API allows a client to submit events in batch.
Create an Event for a Customer
This API offers activity-based request data for creating an event for a customer. This data represents basic activities such as opening an application, and it is associated with metadata tracking an event's date or a count of how many times it occurred. Ultimately, the response data for these events can be presented or utilized in what a customer experiences in an application or on a web site. For example, displaying to the customer the status of a campaign they've accessed or the progress they've made within it.
Endpoints Overview
This API offers three types of endpoints for posting an event. Note that each of the three has two versions of itself: one with an internal user_id and one with an external_id.
The first and most basic set of endpoints is designed to simply create one or multiple events, as shown below:
POST /priv/v1/apps/:api_key/users/:user_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/events The second set of endpoints is designed to create one or multiple events for a specified campaign (via :ad_campaign_id), as shown below:
POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/events The third set of endpoints functions as the previous campaign-related endpoints do but they specify the campaign by a name (via :permalink) instead of an ID, as shown below:
POST /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/events
POST /priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/events Request Data Specification
The characteristics listed above are represented in the request submitted to the Events API.
The primary object in the request is events, which is required and conforms to the following format conditions:
The elements of this format include:
- key is the event name.
- by is an integer for event count or payload data for purchase events.
Consider the following examples:
{"event_name": 1}
{"event_name": {"qty": 1, "store": "A1B2"}}
{"event_name":
[
{"qty": 1, "store": "A1B2"},
{"qty": 1, "store": "C3D4"}
]
}The sections that follow document how to specify event attributes in both simple and complex submissions.
Simple Event Submissions
The following sample demonstrates a simple event submission:
Complex Event Submissions
The complex event submission allows the caller of the API to submit additional metadata related to the event. For example, the following sample request is an event for a customer that downloaded an application:
{
"events": {
"app_downloaded": {
"context" : {
"app_name": "New Cool App",
"version": "1.0",
"downloaded_at": "2019-12-17T17:49:51Z"
}
}
}
}
Within the contents of the request, there is a context payload object. Using it, you can create a request that works in tandem with campaigns where the eligibility is determined by the key/value pair within the context payload object.
For example, an event with the context.version value of 1.0 can have different outcomes than an event where the value is 2.0. This allows the client to design their own event schema (not maintained in the SessionM Platform) that can be easily updated at any time. Currently, the context payload object does not support nested object types. This requires the client to have a flat schema in order to properly use the feature. The current supported types for the values with the context payload object are:
- boolean
- string
- integer
- decimal
- datetime
Note that the event can be matched against all running campaigns or against a particular campaign. You can use one of the following endpoints for that transaction:
POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/events To check the event's eligibility against running campaigns without processing the event, simply add qualify=true to the URL to check whether the event qualifies for a campaign:
POST /priv/v1/apps/:api_key/users/:user_id/events?qualify=true Note that if the occurred_on attribute is omitted, the time zone of the customer is used to determine event's current day.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/events
POST /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/events
POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/events
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
| permalink | Campaign permalink that can be customer-defined or auto-generated. |
| ad_campaign_id | Internal SessionM ad campaign ID. |
| qualify | Checks the event’s eligibility against running campaigns without processing the event. Must be set to true to function. |
| async=true | Causes the event to be processed asynchronously and therefore only a 200 OK response is returned. |
Request Object
When this method runs, it can pass in a request object that contains the events object for basic activity events.
A basic activity event object is shown below:
{
"date": "2016-02-02T17:00:00Z",
"transaction_id": "{{guid}}",
"events": {
"opened_app": 1
}
}Note that only rules associated with a campaign will be processed if ad_campaign_id or permalink is present in the request.
This object is detailed in the table below:
Request Attributes for Events - Basic Activity
| Attribute | Type Required/Optional |
Description |
|---|---|---|
| opened_app | object optional |
Example of a custom event; can be defined for whatever event is being tracked. This event contains two attributes: by (an integer) to specify the count that increments each time the event occurs; and date (a string) to specify the time the event happened; defaults to current time in customer's time zone. Example:{ "date": "2016-02-02T17:00:00Z", "events": { "event_name": 1 } } |
| read_only | boolean optional |
For campaigns that require qualification, when this attribute is set to true, the event's outcome is previewed but NOT processed. Example:{ "read_only": "true", "events": { … } } |
| qualify | boolean optional |
Events sent on behalf of a customer who is not qualified for the campaign get saved but not processed; when qualify is set to true, the events are processed. Example:{ "qualify": true, "events": { "event_name": 1 } } |
| transaction_id |
string |
Idempotency key. Note that when idempotency is enforced by being based on the transaction_id, it is done so per API key. If the same transaction_id is used for the same event from different API keys, both will be processed. UUID format is recommended but not required. |
Response Object
In addition to a status key-value pair, the response object returned by the method contains the following attributes and objects:
- available_points - Amount of points available to customer engaging in purchase event.
- notifications - Array of notifications attributed to the request. Returned notifications can contain a payload along with the message. The payload is a JSON string where any custom information can be supplied. For more information, see Notifications Object.
- user - Data for customer associated with event. For more information, see user.
- behaviors - All active actions for a given application. For more information, see Behaviors Object.
- deltas - Changes attributed to the request by the action. Will display data only when customer and campaign are qualified to run. For more information, see Deltas Object.
- qualified - Indicates whether the event is eligible for running against campaigns. When set to true, the state attribute appears with a status of qualified and the notifications array is empty. When set to false, the state attribute appears with one of the error codes discussed below and the notifications array contains data.
- state - Displays success or error codes pertaining to state of customers or campaigns associated with event.
If qualified attribute discussed above returns true, customer or campaign is qualified and state attribute displays qualified.
However, if qualified attribute discussed above returns false, customer or campaign is not qualified and related error is displayed for state attribute. Possible values include:- campaign_not_started - Campaign attribute starts_at is later than current time.
- campaign_over - Campaign attribute ends_at is before current time.
- not_targeted_to_campaign - Customer not targeted for event.
- events_not_qualified - Customer not qualified for event.
- missing_prerequisites - Customer missing prerequisites.
- reached_frequency_period_cap - Customer reached period cap.
- reached_frequency_cap - Customer reached frequency cap.
Consider the following samples:
{
"status": "ok",
"available_points": 120,
"notifications": [
{
"id": "2cd1c9f8-8471-11e8-8d01-7ed232d1fae9",
"type": "message",
"campaign_id": 313,
"behavior_name": "first_behavior_payload_0",
"data": {
"action_type": "message",
"url": "http://apackard-mbp.i.sessionm.com:3000/apps/e154a4ccba7b84031a1e6fb920acb0f9391cf0c0/users/1d27ebba-1558-11e7-8838-c9b232d1fae9/ads/704",
"message": "Tap Here",
"payload": {
"gift_card_code": "883883-3938292-2928282",
"gift_card_name": "$5 Off Next Purchase"
}
}
}
],
"user": {
"available_points": 120,
"tier": "silver"
},
"behaviors": {
"first_behavior": {
"type": "composite",
"points": 0,
"achieved": 2,
"can_skip": true,
"skipped": 0,
"max_times_repeatable": null,
"max_times_repeatable_per_period": null,
"period": 86400,
"min_time_between_events": null,
"consecutive": false,
"goals": {
"d1f15666_8470_11e8_87a8_427632d1fae9": {
"type": "goal",
"points": 4,
"completed": false,
"required": true,
"earn_count": 1,
"group_id": "0",
"progress": {
"event_name": "d1f15666-8470-11e8-87a8-427632d1fae9",
"type": "count",
"points": 4,
"max_times_repeatable": null,
"max_times_repeatable_per_period": null,
"period": 7776000,
"min_time_between_events": null,
"min_time_between_events_count": 1,
"consecutive": false,
"achieved": 2,
"current_count": 0,
"total_count": 1,
"deltas": {
"current_count": 1,
"achieved": 1
}
}
}
},
"groups": {
"0": {
"type": "group",
"current_count": 0,
"total_count": 1,
"num_goals": 1,
"completed": false
}
},
"deltas": {
"achieved": 1
}
}
},
"deltas": {
"d1f15666_8470_11e8_87a8_427632d1fae9": {
"current_count": 1,
"achieved": 1
},
"first_behavior": {
"achieved": 1
}
},
}Note that the purchase event response above is nearly identical to the response for an activity event. The difference is that the purchase event's value for event_name is a random string ("d1f15666-8470-11e8-87a8-427632d1fae9", shown above), while the activity event's value for event_name is meaningful.
{
"status": "ok",
"available_points": 120,
"notifications": [],
"user": {
"available_points": 120,
"tier": "silver"
},
"behaviors": {
"first_behavior": {
"type": "composite",
"points": 0,
"achieved": 2,
"can_skip": true,
"skipped": 0,
"max_times_repeatable": null,
"max_times_repeatable_per_period": null,
"period": 86400,
"min_time_between_events": null,
"consecutive": false,
"goals": {
"d1f15666_8470_11e8_87a8_427632d1fae9": {
"type": "goal",
"points": 4,
"completed": false,
"required": true,
"earn_count": 1,
"group_id": "0",
"progress": {
"event_name": "d1f15666-8470-11e8-87a8-427632d1fae9",
"type": "count",
"points": 4,
"max_times_repeatable": null,
"max_times_repeatable_per_period": null,
"period": 7776000,
"min_time_between_events": null,
"min_time_between_events_count": 1,
"consecutive": false,
"achieved": 2,
"current_count": 0,
"total_count": 1,
"deltas": {
"current_count": 1,
"achieved": 1
}
}
}
},
"groups": {
"0": {
"type": "group",
"current_count": 0,
"total_count": 1,
"num_goals": 1,
"completed": false
}
},
"deltas": {
"achieved": 1
}
}
},
"deltas": {
"d1f15666_8470_11e8_87a8_427632d1fae9": {
"current_count": 1,
"achieved": 1
},
"first_behavior": {
"achieved": 1
}
},
"qualified": true,
"state": "qualified"
}Notifications Object
This table below provides details on the notifications object, which will contain data when the qualify parameter on the endpoint is unset or set to false:
Response Attributes for Notifications Object Associated with Events
| Attribute | Type | Description |
|---|---|---|
| id | integer | Unique identifier. Example: ad stat id. |
| type | string | Ad type. Example: message,in_app) |
| campaign_id | integer | Ad campaign identifier. |
| data | object | The additional data associated with the notification message payload. |
| action_type | string | Type of action. Example: message,open_ad |
| url | string | The URL of the message. |
| message | string | The body of the message. |
| payload | object | The additional data associated with the ad unit; also called creative content. |
Behaviors Object
This following table provides details on the behaviors object:
Response Attributes for Behaviors Object Associated with Events
| Attribute | Type | Description |
|---|---|---|
| event_name | string | Name of the event. |
| type | string | Type of the object (composite, count, unique). |
| points | integer | Amount of points completing the action is worth. |
| achieved | integer | Total times the action has been completed by a given customer. |
| can_skip | boolean | Indicates whether an action can be skipped or not (true). |
| skipped | integer | Integer value asssociated with skipped action. |
| max_times_repeatable | integer | Number of times an action can be achieved by a given customer overall. |
| max_times_repeatable_per_period | integer | Number of times an action can be achieved by a customer within a defined period. |
| period | integer | Time period in which you want to count events. For example, 1 day, 1 week, 1 month, 90 days. Specify value in seconds. |
| min_time_between_events | integer | Min time period between events. For example, 1 day, 1 week, 1 month, 90 days. Specify value in seconds. |
| min_time_between_events_count | integer | |
| consecutive | boolean | Indicator wether events need to happen on consecutive days |
| current_count | integer | Event count towards completing the action. |
| total_count | integer | Event count required for completing the action. |
| goals | object | Actions associated with composite action. See dedicated table below. |
| deltas | object | Changes attributed to the request. See dedicated table below. |
| groups | object | Action groups associated with the composite action. See dedicated table below. |
The following format applies to this object:
{ behaviors: { behavior_name: {} } }
Note: If ad_campaign or permalink is passed in the request, behaviors are scoped to the ad campaign.
Response Attributes for Goals Object
The goals object contains changes attributed to the Events request and reflects only composite progress.
Format as follows:{ goals: { behavior_name: {} } }
| Attribute | Type | Description |
|---|---|---|
| event_name | string | Name of the event. |
| type | string | Type of the object ("goal") |
| points | integer | Amount of points completing the goal is worth. |
| completed | boolean | Indicator whether the desired customer action (sometimes referred to as a goal) has been completed. |
| required | boolean | Indicator whether the completion of the desired customer action is required to complete the composite action. |
| earn_count | integer | Customer action (sometimes referred to as a goal) count required to complete the composite action. |
| group_id | integer | Index of the group the action belongs to within the composite action. |
| progress | object | Contains all the metadata of the action and associated counts. In effect, a record of the customer's interactions with the action. This object's details about the progress of the action are the same as those attributes described for the Behaviors object associated with a basic activity. Format: {progress: {} }For more information, see the "Response Attributes for Behaviors Object Associated with Events" table above. |
Response Attributes for Groups Object
The groups object contains changes attributed to the Events request and reflects only composite progress.
Format as follows:{ groups: { group_index: {} } }
| Attribute | Type | Description |
|---|---|---|
| type | string | Type of the object ("group"). |
| current_count | integer | Completed goal count within the group. |
| total_count | integer | Total count required to complete the group. |
| num_goals | integer | Number of actions within the group. |
| completed | boolean | Indicator whether the group has been completed. |
Deltas Object
This following table provides details on the deltas object:
Response Attributes for Deltas Object
The deltas object contains changes attributed to the Events request.
| Attribute | Type | Description |
|---|---|---|
| current_count | integer | Change in current_count. |
| achieved | type | Achieved changed. |
| data | array | List of action pivots for a given customer. Reflects only unique progress Example: ['store1','store2'] |
| current_count | integer | Count of action pivots towards earning the action. Reflects only unique progress. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
| Code | Reason |
|---|---|
| missing_event_data | Event data is missing from request. |
| No_active_campaign_found | No campaign was found matching the request criteria. |
|
transaction_id #{TRANSACTION_ID} has already been processed |
Event has been submitted twice with the same transaction_id (using same set of API keys). Code: 409. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Retrieve Events for a Customer
Retrieves events for a customer, including reward balances as well as action and progress data for the customer's events
Endpoints
This method offers the following endpoints:
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains an attribute and another object, as shown below:
{
"status": "ok",
"available_points": 0,
"behaviors": {
"behavior_name": {
"event_name": "event_name",
"type": "count",
"max_times_repeatable": "nil",
"max_times_repeatable_per_period": "nil",
"min_time_between_events": "nil",
"consecutive": false,
"achieved": 0,
"current_count": 0,
"total_count": 2
}
}
}It begins with a status key-value pair that provides the status of the transaction. The next line in the response specifies the available_points key-value pair, which indicates how many loyalty points are available to the customer.
The response object also contains the behaviors object.
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.