Usage¶
To use the ntokloapi connector you just need to import it:
import ntokloapi
Then you will have access to the different parts of the API. Remember that to interact with the API you will need a valid API key and API secret.
Universal Variable¶
The nToklo recommendation engine uses UV (Universal Variable) objects to create the recommendations. UV is a type of JSON object that has a specific set of keys to manage ecommerce entries. You can check the specification here.
Products¶
To keep track of the products, you have to send them first. It’s not a requirement but if you have a big catalog it will allow you to preprocess the data before starting to send events.
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | import ntokloapi
uv = {
"version": "1.2", # If this doesn't exist, the connector will assume latest
"product": {
"id": "10201",
"category": "Shoes",
"manufacturer": "Nike",
"currency": "GBP",
"unit_sale_price": 98
},
}
product = ntokloapi.Product(MyAPIKey, MyAPISecret)
# If you want to send the product straight to the API
product.create(uv)
# In case you want to check the response
response = product.create(uv)
print(response) # HTTP 204 is the expected output
|
Events¶
An event in the nToklo recommendation system means some kind of action that has performed by the user.
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | import ntokloapi
# This UV is a bit special. You can send the minimum data as in the
# example, but you can expand it with the whole information about the
# product and the user if you want. That way if the product doesn't exist
# it will be automatically created in the API.
uv = {
"version": "1.2", # If this doesn't exist, the connector will assume latest
"user": {
"user_id": "112"
},
"product": {
"id": "10201",
},
"events": [
{
"action": "preview",
"category": "conversion_funnel"
}
]
}
event = ntokloapi.Event(MyAPIKey, MyAPISecret)
# In case you want to send it straight to the API
event.send(uv)
# In case you want to check the response
response = event.send(uv)
print(response) # HTTP 204 is the expected output
|
Recommendations¶
This is the core of the system, the recommendations. This function will return to you a JSON object with the recommended products for your user and a temporary token.
Example:
1 2 3 4 5 6 | import ntokloapi
recommendation = ntokloapi.Recommendation(MyAPIKey, MyAPISecret)
recommendations = recommendation.get(productid='10201')
print(recommendations)
|
It should return something like this:
1 2 3 4 5 6 7 8 9 10 | {
"tracker_id": "1d9042f0-32d3-11e5-88b8-19d6b5557055",
"items": [
{
"id": "10201",
"category": "Shoes",
"manufacturer": "Nike"
}
]
}
|
Blacklist¶
The blacklist functionality allows you to add products to a blacklist so they don’t show up on the recommendations.
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | import ntokloapi
blacklist = ntokloapi.Blacklist(MyAPIKey, MyAPISecret)
# Add one product to the blacklist
blacklist.add(['10201',])
# Add multiple rpoducts to the blacklist
blacklist.add(['10201', '10202', '10203'])
# Remove a product from the blacklist
blacklist.remove(['10203',])
# Remove multiple products from the blacklist
blacklist.remove(['10201', '10202'])
# List all the currently blacklisted products
blacklisted_products = blacklist.list()
print(blacklisted_products)
|
Charts¶
Charts allows you to pull information regarding your analytics. It’s not a full report, for that you will have to use the nToklo Console. Charts contains a number of options that will be useful to you for filtering the information. Please refer to the Reference.
1 2 3 4 5 6 | import ntokloapi
charts = ntokloapi.Chart(MyAPIKey, MyAPISecret)
analytics = charts.get(date='1364169600000')
print(analytics)
|