Tutorials Custom Events and Fields

Custom Events and Fields

The goal of sending custom events and fields is to

  1. Capture key events and data points not covered by our reserved events and fields.
  2. Give your fraud prediction model more ways to distinguish between the traits and behaviors of good and bad users so that it can more accurately find fraudsters.
  3. Give your fraud prediction model more ways to distinguish between items, services, posts, etc, so that it can determine
    • which are more attractive to fraudsters
    • which are more likely created by fraudsters
  4. Give your fraud team additional, useful ways to sort through users in the console.

For example, let's say you have a voice over IP phone business, and you want to record when a user makes a call. You can create a custom event called make_call as shown.

Three fields are required in custom events: $type, $api_key, and the $user_id or $session_id which identifies the user taking the action.

// A hypothetical custom event recording a call made
// using a number of formatted fields
{
  "$type"              : "make_call",
  "$api_key"           : "YOUR_API_KEY",
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "call_duration"      : 4428
}

import sift

client = sift.Client(api_key='{apiKey}', account_id='{accountId}')

# A hypothetical custom event recording a call made
# using a number of formatted fields
properties = {
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "call_duration"      : 4428
}

response = client.track("make_call", properties)

require "sift"

client = Sift::Client.new(:api_key => "YOUR_API_KEY")

# A hypothetical custom event recording a call made
# using a number of formatted fields
properties = {
  "$user_id"           => "billy_jones_301",
  "recipient_user_id"  => "marylee819",
  "call_duration"      => 4428
}

response = client.track("make_call", properties)

require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'YOUR_API_KEY'));

// Sample $link_session_to_user event
$properties = array(
  '$user_id'           => 'billy_jones_301',
  'recipient_user_id'  => 'marylee819',
  'call_duration'      => 4428
);

$response = $client->track('make_call', $properties);

import com.siftscience.SiftClient;
import com.siftscience.EventRequest;
import com.siftscience.model.CustomEventFieldSet;

SiftClient client = new SiftClient("YOUR_API_KEY");
EventRequest request = client.buildRequest(new CustomEventFieldSet()
        .setUserId("billy_jones_301")
        .setEventType("make_call")
        .setCustomField("recipient_user_id", "marylee819")
        .setCustomField("call_duration", 4428)
);

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}

response.isOk(); // true

Naming Custom Events

In general, events sent to our Events API should describe a particular action taken by a user. We encourage starting the name of your custom events with a verb in present tense, e.g. add_new_connection or create_new_location.

Custom event names may only include alphanumeric characters and _.

We encouage you to adopt our naming conventions in creating custom event and custom field names. We use lower case and snake_case for all event and field names.

Special field suffixes

Send fields using our reserved suffixes when possible to take advantage of additional analysis.