Behavioral API

The Behavioral API provides a scalable framework for sending event data to Cortex’s servers in real-time. Events are the required building blocks for any Machine Learning Pipeline in Cortex, and the Behavioral API allows you to stream these events to Cortex as they occur. The more data submitted to the Behavioral API, the wider the set of predictions you can make and the more accurate your predictions will be.

The following sections will describe how to POST event data to the Behavioral API.

Event Parameters

The following table outlines the parameters to send alongside each event. Note that this table assumes a Cortex account that is configured to make predictions about users. If your account is set to predict for any other type of object, you should substitute the appropriate ID (e.g. item_id) for the “user_id” field.

Note that if you’d like to generate personalized item recommendations for each user, or if you are sending Items data into Cortex, your events must also contain an item ID indicating which item the user interacted with. For recommendations, you should also be sure to send impression events (i.e. “shown”) to indicate when a user is exposed to an item.

When sending ‘shown’ events (i.e. impressions), Cortex recommends adhering to the following best practices, which are based on guidelines from the Interactive Advertising Bureau.

• A ‘shown’ event should only be sent if at least 50% of the item is visible for at least 1 second.
• A ‘shown’ event should only be sent once per item per page load.

Sending Behavioral Events

The process of sending a behavioral event is summarized by the following steps:

Step 1: Build an array of event objects.

This array can contain one or multiple events. Create a hash with the required and optional parameters for each event, similar to the following example:

events = {   
    data: [{     
      user_id: "123",     
      item_id: "ABC",     
      type: "purchase",
      device: "mobile",
      sale_price: 49.99
    }]
}

Step 2: Serialize the events array with JSON.

Convert your events array into a JSON string, like the following example:

serialized_events = '{"data":[{"user_id":"123","item_id":"ABC","type":"purchase","device":"mobile","sale_price":49.99}]}'

Step 3: Generate a signature, if necessary.

Signatures may be disabled for the Behavioral API. However, if the Behavioral API is configured to require a signature with each POST, follow Steps 1-5 in the Generating a Signature section. Note that signatures are validated during processing rather than in real-time.

Step 4: POST the data to Cortex’s servers.

Send the POST with your serialized data to http://a.vidora.com/v1/validate. HTTPS is also supported.

The POST body should include a JSON-serialized string containing a key-value pair with the string ‘data’ and your events. Depending on whether a signature is included in your request, the final POST request might look like one of the following:

Example POST without Signature

POST https://a.vidora.com/v1/validate?api_key=<YOUR_KEY>

Content-Type: application/json
'{"data":[{"user_id":"123","item_id":"ABC","type":"purchase","device":"mobile","sale_price":49.99}]}'

Example POST with Signature

POST https://a.vidora.com/v1/validate?api_key=<YOUR_KEY>&expires=2016-0101T00%3A00&signature=YOUR_SIGNATURE

Content-Type: application/json
'{"data":[{"user_id":"123","item_id":"ABC","type":"purchase","device":"mobile","sale_price":49.99}]}'

Note that sending behavioral events to Cortex’s servers will always return a 200 HTML response code, indicating a successful POST. To verify that the correct data has been posted to Cortex’s severs in the correct format, or for any additional questions or information, please contact support@mparticle.com.

Related Links

• Events Data
• JavaScript SDK Behavioral Module
• Batched File Uploads
• Items API

Still have questions? Reach out to support@mparticle.com for more info!