Behavioral API

The Behavioral API provides a scalable framework for sending event data to Vidora’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.

Param Required? Value Description
user_id Yes string An ID which uniquely identifies the user that completed the event
type Yes string The type of event performed by the user (e.g. “click”, “purchase”, etc.).
timestamp No integer The default timestamp for an event is the time an event is submitted.
However, you may specify a different timestamp for when the event actually occured.
The timestamp should be expressed in seconds since epoch (January 1, 1970 at 00:00:00 UTC).
<custom_param> No boolean
float
integer
string
timestamp
Optionally, include any other parameters containing information about the events that you’re sending. These fields could describe the user completing the event (e.g. gender=female), the item/page on which the event was recorded (e.g. item_id=XYZ), or conditions of the event itself (e.g. device=mobile).

 

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",     
      content_id: "1",     
      type: "like",
      like: 1
    }]
}

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","content_id":"1","type":"like","like":1}]}'

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.

Step 4: POST the data to Vidora’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","content_id":"XYZ","type":"like","like":1}]}'

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","content_id":"1","type":"like","like":1}]}'

When sending ‘shown’ events, Vidora recommends adhering to the following best practices, which adhere to impression 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.

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

Related Links

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

Table of Contents