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.

Some example outcomes that can be triggered when an event achieves a campaign behavior 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

This API provides the following groupings of methods:

• Send an event for a customer (V1)
• Send an event for a customer (V2)
• Retrieve events for a customer

The V1 and V2 versions of methods for sending events differ in a few important respects.

Version 1 of the Events API offers methods that can optionally accept a campaign identifier as either an ID or as a permalink. This provides clients with the ability to send an event for one or more campaigns. By default, this API processes synchronously. But the send endpoint does contain an async parameter, a flag you can use to ensure events are processed asynchronously. For more information, see this Endpoint Parameters table, or consult with your implementation team to decide which is a better fit for your use cases and implementation architecture.

Version 2 of the Events API offers methods that always process asynchronously. No flag needs to be set. The API provides the ability to submit events for multiple customers in a single request.

Note that both versions 1 and 2 of the Events API are designed to support idempotency, thereby ensuring that no event instance would be ingested more than once. For more information, see this discussion on idempotency.

Before you begin working with one of the methods listed above, consider the conceptual information detailed 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.

Send an Event for a Customer (V1)

This API offers activity-based request data for sending 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:

REST Endpoints (Send Event(s))

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 send one or multiple events for a specified campaign (via :campaign_id), as shown below:

REST Endpoints (Send Event(s) for a Campaign)

POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:campaign_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/: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:

REST Endpoints (Send Event(s) for a Campaign by Name)

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:

Request Data (Event(s))

{"events": {"key": "by"}}

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:

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:

Simple Event Submission

{
    "events" : { "opened_app": 1 }
}

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:

Complex Event Submission

{
  "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:

Endpoints Matching Event to Campaign

POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:campaign_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/: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:

Endpoints Checking Event Eligibility Against 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.

Multi-Org Event Submissions

When multi-org is enabled, the API supports the submission of additional metadata related to the event that indicates what organization the event is associated with. The value for this division ID attribute is defined during Organization Management configuration. When submitting an event for an organization, the request object contains the following information:

Organization Event Submission

{
    "events": {
        "test_event_1": {
            "context" : {
                "some_property" : "foo",
                "division_id" : "gbr"
            }
        }
    }
}

The context object contains a single division ID.

When multi-org is enabled, the event is considered only by campaigns that correspond to the provided division ID and their ascendent divisions. If there is a mismatch between the event's division ID and the user's division ID, the event will be processed but won't qualify for progress in any campaigns since the user won't qualify based on audience targeting. For example, the Events API caller provides the GBR division in the event context, but the user in the API request is assigned to the FRA division. In this case, the user is not eligible for any GBR campaigns. So the event is processed but it is effectively ignored by any campaign.

With respect to validation and error handling, when multi-org is enabled, the endpoint validates division_id against the multi-org configuration and returns the 400 bad request error code if the provided value is not a valid division ID. When the parameter is missing, event processing defaults to the root division of the configuration. When multi-org is disabled, the endpoint ignores the division _id parameter.

Endpoints for Send an Event for a Customer (V1)

This method offers the following endpoints:

REST 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/: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/: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 for Send an Event for a Customer (V1)

The following parameters are available when specifying the endpoint for this method:

Request Object for Send an Event for a Customer (V1)

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:

JSON Request for Basic Activity Event (Opening an App)

{
    "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 campaign_id or permalink is present in the request.

This object is detailed in the table below:

Request Attributes for Events - Basic Activity

Response Object for Send an Event for a Customer (V1)

In addition to a status key-value pair, the response object returned by the method contains the following attributes and objects:

• available_points - DEPRECATED attribute.

• 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:

JSON Response for Purchase Event with Qualify Parameter NOT Set

{
    "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.

JSON Response for Purchase Event with Qualify Parameter Set

{
                "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

Behaviors Object

This following table provides details on the behaviors object:

Response Attributes for Behaviors Object Associated with Events

The following format applies to this object:

{ behaviors: { behavior_name: {} } }

Note: If 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: {} } }

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: {} } }

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.

Statuses and Errors for Send an Event for a Customer (V1)

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:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Send an Event for a Customer (V2)

Like its V1 counterpart, this V2 API offers activity-based request data for creating an event for a customer. However, this API always processes events asynchronously, sending events from a queue. In addition, this API can submit events for multiple customers in a single request.

Endpoints for Send an Event for a Customer (V2)

This method offers the following endpoint:

REST Endpoints

POST /priv/v2/apps/:api_key/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 for Send an Event for a Customer (V2)

The following parameters are available when specifying the endpoint for this method:

Request Object for Send an Event for a Customer (V2)

When this method runs, it can pass in a request object that contains the events object for basic activity events. This object can hold one or many events.

A simple event payload is shown below:

JSON Request for Simple Event (Opening an App)

{
                "events": {
                    "name": "opened_app",
                    "by": "1",
                    "external_id": "user_external_id"
                }
}

If you want to add multiple events, the events must be specified in an array structure:

JSON Request for Multiple Events

{
                "events": [
                    {
                        "name": "opened_app",
                        "by": "1",
                        "external_id": "user_external_id"
                    }
                ]
}

High throughput of events can cause delays in their processing. In order to keep processing delays to a minimum, keep the number of events below 100 per request.

This request can also contain a context payload object, as shown below:

JSON Request for Event with Context (Opening an App)

{
                "events":
                [{
                    "name": "opened_app",
                    "by": "1",
                    "external_id": "user_external_id",
                    "context" :
                    {
                        "app_name": "user_external_id",
                        "version": "1.0",
                        "downloaded_at": "2019-12-17T17:49:51Z"
                    }
                }]
}

The context object allows you to create a request that works in tandem with campaigns where the eligibility is determined by the key/value pair, which is also with the context.

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 - one that is not maintained in the SessionM Platform and can be easily updated. 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 events object, along with the context object, is detailed in the tables below:

Request Attributes for Events

See the table below for details on the context object:

Attributes for Context

The current supported types for context object attributes include:

• boolean
• string
• integer
• decimal
• datetime

Response Object for Send an Event for a Customer (V2)

The response object contains a status key-value pair for a 200 OK status if successful, as shown below:

JSON Response for Sending an Event

{
        "status": "ok"
}

Statuses and Errors for Send an Event for a Customer (V2)

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:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Note on Idempotency

The Events V2 API can be idempotent. In order to enable the functionality, the event must be provided along side a unique string denoted as a transaction_id.

Consider the following example:

JSON Request for Sending an Event with Idempotency

{
    "events":
    [{
        "name": "opened_app",
        "by": "1",
        "external_id": "user_external_id",
        "transaction_id": "ca98e52a-bcef-11ed-8bbd-7946ac180007",
        "context":
        {
            "app_name": "New Cool App",
            "version": "1.0",
            "downloaded_at": "2019-12-17T17:49:51Z"
        }
    }]    }
}

Using the transaction_id ensures that the SessionM platform does not ingest an event instance multiple times.

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 for Retrieve Events for a Customer

This method offers the following endpoints:

REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_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 for Retrieve Events for a Customer

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve Events for a Customer

Not applicable.

Response Object for Retrieve Events for a Customer

In addition to a status key-value pair, the response object returned by the method contains an attribute and another object, as shown below:

JSON Response

{
  "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 for Retrieve Events for a Customer

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.