Triton is the world's best personalization engine. By tracking your users' behaviors on your site, we can learn about their preferences and show them content they'd love.

Follow the guides below to walk you through common use cases. Check out the reference tab for specific function definitions, and don't hesitate to reach out for specific customization of the API!

Quickstart

Start by logging into Triton to get your API-key, and use that to instantiate a Triton object.


<html> 
  <head> 
    <script src="https://triton.cloud/cdn/triton.min.js">
    </script> 
    ... 
  </head> 
  ... 
</html>

var client = triton.Client(<your-api-key>);

import triton
client = triton.Client(<your-api-key>)

Once you have your Triton object, you're 3 short steps away from WOW-ing your users.

  1. Upload catalog of users/items
  2. Track user engagements
  3. Receive recommendations

1) Upload catalog of users/items

In order to make recommendations, it'll be helpful to know a bit about your users and items. With the metadata you deem helpful, upload all your existing users and item; whenever a new user or item is created, push that new object to Triton with the same line of code.


client.uploadUser("ID-440", {"gender": triton.String("M"), "age": triton.Number(3)});
client.uploadItem("ID-099", {"title": triton.String("hilarious video"), "views": triton.Number(20000)});

client.upload_user(id="ID-440", properties={"gender": triton.String("M"), "age": triton.Number(3)})
client.upload_item(id="ID-099", properties={"title": triton.String("hilarious video"), "views": triton.Number(20000)})

Learn more about using types and building schemas in our guides below.

2) Track user engagements

To learn about what your users like, we need to know what they do on your app. Whenever a user clicks, likes, or purchases an item, let us know with the collect methods.


client.itemClick("user-ID-440", "item-ID-099");
client.itemAction("purchase", "user-ID-440", "item-ID-099");

client.item_click(user="ID-440", item="ID-099")
client.item_action(action="purchase", user="ID-440", item="ID-099")

3) Recieve Recommendations

Our models take a few days to maximize your results. When they're ready, you can use these methods to recieve top-notch recommendations.


// 10 is the number of recommended items to return
var recs = client.recommend("user-ID-440", 10);

# num is the number of recommended items to return
recs = client.recommend(user="ID-440", num=10)

Specifying Datatypes

For uploading rows of objects, you must declare the types of each parameter in one of the following 2 ways:

  1. Before uploading a row of data, define your schema.
  2. Upload data right away, casting each parameter-value everytime you upload a row.

Option 1. Declare types in schema

Before uploading any data, you can define the schema. Check the reference page for clarification on each type.


// let's say items are videos
client.setItemSchema({"views": triton.NumberType(), "date": triton.DateType(), "playlist": triton.IDType()});
client.uploadItem("9992", {"views": 122, "date": "2018-02-01", "playlist": "9912100"});

# let's say items are videos
client.set_item_schema({"views": triton.NumberType(), "date": triton.DateType(), "playlist": triton.IdType()})
client.upload_item(id="9992", properties={"views": 122, "date": "2018-02-01", "playlist": "9912100"})

Note: do not include the primary key field in schema declarations, as this will be automatically added.

The types StringType, TextType, NumberType, DateType, and EnumType do not expect any arguments in their constructor. The ArrayType expects a string argument specifying the type of each element in the array. You can do some exciting stuff with IDType, so check out the ID guide.


Option 2. Type-cast in each row-upload

You can skip the set-schema step and just wrap each parameter value with their corresponding type on each upload call. Check the reference page for clarification on each type.


// let's say items are text articles
client.uploadItem("4447", {"title": triton.String("10 best ways to use orange peels"), "views": triton.Number(0), "date": triton.Date("2018-02-01"));

# let's say items are articles
client.upload_item(id="4447", properties={"title": triton.String("10 best ways to use orange peels"), "views": triton.Number(0), "date": triton.Date("2018-02-01"))

You must pass the value of the parameter in each type. For String, Text, Number, Date, and Enum, parameter-value is the only expected argument. The first argument of the Array wrapper specifies the type of each element in the array, and the second argument is the parameter value. Check the ID guide below to better understand the ID wrapper.

IDType and ID Wrapper

If a certain parameter of your users or items is an ID-type, many of them will be foreign key references to other tables. If it is not, the ID-type is treated like all other types: IDType() takes no arguments and ID wrapper only expects the parameter value.


IDType - for use in set-schema methods

// let's say items are clothes
client.setSchema("materials", {"name": triton.StringType(), "warmth": triton.NumberType()});
client.setItemSchema({"name": triton.StringType(), "material": triton.IDType("materials"), "color": triton.EnumType(), "brand": triton.String()});
// after setting the schema, upload some rows
client.upload("materials", "2221", {"name": "polyester", "warmth": 0.3);
client.uploadItem("7773", {"title": "V-neck Shirt", "material": "2221", "color": "black", "brand": "Ed Hardy");

# let's say items are clothes
client.set_schema("materials", {"name": triton.StringType(), "warmth": triton.NumberType()})
client.set_item_schema({"name": triton.StringType(), "material": triton.IDType("materials"), "color": triton.EnumType(), "brand": triton.String()})
# after setting the schema, upload some rows
client.upload("materials", "2221", {"name": "polyester", "warmth": 0.3)
client.upload("7773", {"title": "V-neck Shirt", "material": "2221", "color": "black", "brand": "Ed Hardy")

Note: do not include the primary key field in schema declarations, as this will be automatically added.


ID wrapper - for use in upload methods

// let's say items are clothes
client.upload("materials", "2221", {"name": triton.String("polyester"), "warmth": triton.Number(0.3)});
client.upload("7773", {"title": triton.String("V-neck Shirt"), "material": triton.Id("2221", "materials"), "color": triton.Enum("red")});

# let's say items are clothes
client.upload("materials", "2221", {"name": triton.String("polyester"), "warmth": triton.Number(0.3)})
client.upload_item("7773", {"title": triton.String("V-neck Shirt"), "material": triton.Id("2221", "materials"), "color": triton.Enum("red")})

If that ID parameter is a foreign key, you can give Triton additional information about that foreign table using the schema guide below. Once you do that, you simply specify the name of that foreign schema in each ID type.

Schema Options

By default, you will start with 2 schemas: users and items. Items are the objects on your application that we will be suggesting for your users. Let's walk through 3 possible schema set ups:

  1. Basic users and items with no metadata
  2. Users and items with metadata
  3. Adding additional Schemas

1. Basic users and items with no metadata

Let's say you only have user-ID's and item-ID's and you want to generate recommendations. That's easy! Just set up click listeners, and recieve recommendations.


// set up click listeners
client.itemClick("user9292", "item5454");
// in another location, get recommendations
client.recommend("user9292");

# set up click listeners
client.item_click(user="9292", item="5454");
# in another location, get recommendations
client.recommend(user="9292"); 

2. Users and items with metadata

As covered in the quickstart, many of you will have some metadata properties on users and items that you can upload before we track user behaviors. In this case, you can follow the quickstart to upload users and items, set up click listeners, and then recieve recommendations.


3. Adding additional schemas

We highly encourage you to tell Triton a bit more about users and items. If one of the parameters for an item is a foreign-key to a different table, you can upload some of that foreign-table as well to improve your recommendations! This will be particularly heplful for solving cold start.

Let's walk through an example. Let's say you are an online marketplace that connects house-renters with long-term rentals. Users are renters and items are apartments. Your data look like this:

Renters/Users
user_id UUID,
gender varchar(256),
age int,
joined date
Apartments/Items
apt_id UUID,
city UUID references Cities(id),
housing_type varchar(256),
owner varchar(256)
Cities
id UUID,
name varchar(256),
state varchar(256),
num_listings int

You know how to upload the users and items from the guides above, but how do you deal with this additional property, Cities? It's quite simple, actually. Just set up that schema and upload rows in the same way you would for users and items.


// set up the schemas
client.setSchema("users", {"gender": triton.StringType(), "age": triton.NumberType(), "joined": triton.DateType()});
client.setSchema("Cities", {"name": triton.StringType(), "state": triton.StringType(), "num_listings": triton.NumberType()});
client.setSchema("items", {"city": triton.IdType("Cities"), "housing_type": triton.StringType(), "owner": triton.StringType()}});
// after setting the schema, upload some rows
client.upload("users", "8884", {"gender": null, "age": "23", "joined": "2018-02-01T13:43:12");
client.upload("Cities", "6661", {"name": "Fresno", "state": "CA", "num_listings": 45);
client.upload("items", "1110", {"city": "6661", "housing_type": "duplex", "owner": "Donald Duck");
// then set up click-listeners and recieve recommendations!

# set up the schemas
client.set_schema("users", {"gender": triton.StringType(), "age": triton.NumberType(), "joined": triton.DateType()})
client.set_schema("Cities", {"name": triton.StringType(), "state": triton.StringType(), "num_listings": triton.NumberType()})
client.set_schema("items", {"city": triton.IdType("Cities"), "housing_type": triton.StringType(), "owner": triton.StringType()}})
# after setting the schema, upload some rows
client.upload("users", "8884", {"gender": None, "age": "23", "joined": "2018-02-01T13:43:12")
client.upload("Cities", "6661", {"name": "Fresno", "state": "CA", "num_listings": 45)
client.upload("items", "1110", {"city": "6661", "housing_type": "duplex", "owner": "Donald Duck")
# then set up click-listeners and recieve recommendations!

Note: you don't have to specify the ID-field when specifying your schema.

As you may have noticed, the set-schema method has 2 convenient aliases: set-item-schema and set-user-schema. Similarly, upload has 2 aliases: upload-ttem and upload-user. Both of these behave just like the generalized version, so you can add as many schemas as you want referenced by any number of parameters.