Permalink
Browse files

Transferred docs to github

  • Loading branch information...
1 parent e2cc9f8 commit 5939840730dcfd0744921bc8107695854da19b41 Ovidiu Beldie committed Jul 21, 2016
View
@@ -0,0 +1 @@
+# Created by .ignore support plugin (hsz.mobi)
View
@@ -1,2 +1,41 @@
-# docs
-Documentation on APIs, integration, plugins
+![www.ntoklo.com](https://cloud.githubusercontent.com/assets/1387097/17018478/d6fa453c-4f2f-11e6-966f-40d728dd5030.png)
+
+# Welcome!
+
+This documentation will guide you through the integration process with the nToklo platform, either as a plugin user or when going for an API integration.
+
+## nToklo plugins
+The plugins allow even non-technical administrators to leverage the nToklo recommendations platform with just a few simple installation steps.
+
+Currently, we provide plugins for:
+
+- [Magento](doc/plugin/magento.md)
+- [Wordpress](doc/plugin/wordpress.md)
+- [WooCommerce](doc/plugin/woo_commerce.md)
+
+## API integration
+If no plugin is available for your platform, you'll have to write some code to integrate with our API. It's more straightforward than you might think! The following sections will give you all the details:
+
+1. [Getting Started](doc/api/getting_started.md)
+2. [Basic Integration](doc/api/basic_integration.md)
+3. [nToklo API](doc/api/api.md)
+4. [POST-ing events](doc/api/js.md)
+5. [Authentication](doc/api/auth.md)
+6. [Support for Analytics](doc/api/analytics.md)
+
+To render the application process even more simple, we created a library (or "connector"), available in the the most commonly used languages, that abstracts the communication process with the nToklo API:
+
+- [PHP connector](doc/api/php_connector.md)
+- [Python connector](doc/api/python_connector.md)
+
+
+## Support
+- [FAQ](doc/faq.md)
+
+Do you need help getting nToklo integrated? Would like to discuss what integration option is best for you?
+
+Get in touch at support@ntoklo.com and we'll be more than happy to help.
+
+
+
+
View
@@ -0,0 +1,105 @@
+![www.ntoklo.com](https://cloud.githubusercontent.com/assets/1387097/17018478/d6fa453c-4f2f-11e6-966f-40d728dd5030.png)
+# Clickthrough Analytics
+
+In order for nToklo to provide clickthrough and conversion analytics, you must include clickthrough events in the UV objects sent to nToklo servers.
+
+This is an optional, and advanced feature; but the benefits are worth the effort to support it.
+
+## 1. Impressions
+The first step is to fetch a recommendation set. You will receive an array of recommended items as well as a `tracker_id`.
+
+`GET /recommendation?productId=12014`
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=utf-8
+
+{
+ "tracker_id": "2b169680-aa86-12e5-9c37-600308a4f234",
+ "items": [
+ {
+ "id": "10242",
+ "name": "MOTO Frayed Daisy Hotpant",
+ "currency": "GBP",
+ "unit_sale_price": 22,
+ ...
+ },
+ { ... }
+ ]
+}
+```
+
+Now you want to render the recommendation set on the page; let's say it's a product page. You want the `universal_variable` object to include the impression event with the `tracker_id`, so the UV object will look as follows:
+
+```
+{
+ "version": "1.2",
+ "events": [
+ {
+ "category": "conversion_funnel",
+ "action": "preview"
+ },
+ {
+ "category": "clickthrough_goals",
+ "action": "recommendation-impr",
+ "tracker_id": "2b169680-aa86-12e5-9c37-600308a4f234"
+ }
+ ],
+ "product": {
+ "id": "10772",
+ "name": "Navy Folk Scarf Print Shorts",
+ "currency": "GBP",
+ "unit_sale_price": 32,
+ ...
+ },
+ "user": {
+ "user_id": "beth89"
+ },
+ "page": {
+ "type": "product",
+ "breadcrumb": ["Home", "Women", "Shorts"]
+ }
+}
+```
+
+Notice that the impression event is simply appended to the `events` array. Clickthrough events are indicated by the category clickthrough_goals. If you fetch a recommendation set, the corresponding action should be `recommendation-impr`. If you fetch a chart, the action should be `chart-impr`.
+
+## 2. Clicks
+The click event is just as simple to implement. When a user clicks on a recommended item, the tracker_id should be forwarded to the resulting page. It is up to you how to forward the tracker_id but it is typical to simply pass it through via request parameter, e.g.:
+
+`http://fashionbay.com/product?id=10242&nt_tracker=2b169680-aa86-12e5-9c37-600308a4f234`
+
+When the UV object renders on the resulting page, you want it to include the click event with the tracker_id. In this example we passed the tracker_id through via arbitrary request parameter. So the UV looks as follows:
+
+```
+{
+ "version": "1.2",
+ "events": [
+ {
+ "category": "conversion_funnel",
+ "action": "preview"
+ },
+ {
+ "category": "clickthrough_goals",
+ "action": "recommendation-click",
+ "tracker_id": "2b169680-aa86-12e5-9c37-600308a4f234"
+ }
+ ],
+ "product": {
+ "id": "10242",
+ "name": "MOTO Frayed Daisy Hotpant",
+ "currency": "GBP",
+ "unit_sale_price": 22,
+ ...
+ },
+ "user": {
+ "user_id": "beth89"
+ },
+ "page": {
+ "type": "product",
+ "breadcrumb": ["Home", "Women", "Shorts"]
+ }
+}
+```
+
+Notice that the click event looks similar to the impression event, except the action is `recommendation-click`. Similarly, if you had fetched a chart the action would be `chart-click`.
View
@@ -0,0 +1,13 @@
+![www.ntoklo.com](https://cloud.githubusercontent.com/assets/1387097/17018478/d6fa453c-4f2f-11e6-966f-40d728dd5030.png)
+#nToklo API
+
+The nToklo API will help you provide a personalised experience for you customers. Integrate your [UV](http://docs.qubitproducts.com/uv/intro/) objects with the Events API, and fetch product recommendations and charts.
+
+Explore our APIs:
+
+- [Events](events.md)
+- [Recommendations](recommendations.md)
+- [Charts](charts.md)
+- [Products](products.md)
+- [Blacklist](blacklist.md)
+- [Search](search.md)
@@ -0,0 +1,31 @@
+![www.ntoklo.com](https://cloud.githubusercontent.com/assets/1387097/17018478/d6fa453c-4f2f-11e6-966f-40d728dd5030.png)
+# Asynchronous events
+
+Some events occur asynchronously, i.e. not on page load. A typical example is a rate, favourite, or like interaction. Such actions often involve clicking a button and updating the DOM asynchronously. In such cases you can send UV objects asynchronously by invoking window.ntoklo.sendEvent.
+
+Here's an example:
+```javascript
+<script type="text/javascript" src="https://console.ntoklo.com/static/js/ntoklo.js"></script>
+<script type="text/javascript">
+ /* construct UV object representing the asynchronous event */
+ var eventObject = {
+ "events": [
+ {
+ "category": "conversion_funnel",
+ "action": "rate"
+ }
+ ],
+ "user": {
+ "user_id": "8492834083"
+ },
+ "product": {
+ "id": "ABC123",
+ "manufacturer": "Acme Corp",
+ "category": "Shoe"
+ }
+ }
+
+ /* send the event, triggered by a click event or something similar */
+ window.ntoklo.sendEvent(eventObject);
+</script>
+```
View
@@ -0,0 +1,59 @@
+![www.ntoklo.com](https://cloud.githubusercontent.com/assets/1387097/17018478/d6fa453c-4f2f-11e6-966f-40d728dd5030.png)
+
+## Server-side authentication
+
+Server-side requests to the nToklo API must be signed using SHA1-HMAC and your API secret. For example, to fetch recommendations using a signed request to authenticate:
+
+### Step 1. Produce the request signature
+
+- Construct a basestring from the request. Notice the format of the basestring, `<HTTP_METHOD>&<REQUEST_URI>`:
+`GET&https://api.ntoklo.com/recommendation?userId=112&productId=10201`
+
+- Construct a key to be used for SHA1 encryption; it should have the format `client_key&client_secret`:
+`YzZkYmI2ZGUtYTNiYS00NWQ5LThjOWMtODZiZDBhNzljZjM5&MmExMzY0ZGUtMjc0ZS00NWMyLWExNDMtM2U3OTc4ODljODI2`
+
+- Base64 encode the resulting HMAC_SHA1 hash. This is your request signature:
+`1d0570f3c1995bfa3974a35731b17ecb51f6b6fb`
+
+Here’s a code example of signing a request using the Python Interpreter:
+
+```
+>>> import hmac
+>>> from hashlib import sha1
+>>> client_key = "YzZkYmI2ZGUtYTNiYS00NWQ5LThjOWMtODZiZDBhNzljZjM5"
+>>> client_secret = "MmExMzY0ZGUtMjc0ZS00NWMyLWExNDMtM2U3OTc4ODljODI2"
+>>> uri = "https://api.ntoklo.com/recommendation?userId=112&productId=10201"
+>>> http_method = "GET"
+>>> basestring = "%s&%s" % (http_method, uri)
+>>> sha1_key = "%s&%s" % (client_key, client_secret)
+>>> signature = hmac.new(sha1_key, basestring, sha1).hexdigest()
+>>> print signature
+1d0570f3c1995bfa3974a35731b17ecb51f6b6fb
+>>>
+```
+
+### Step 2. Authorisation header
+In order for your request to be authenticated you must provide the Authorization header, which should contain you API key and request signature in the format client_key:signature. The authorisation realm should be NTOKLO.
+
+```
+GET /recommendation?userId=112&productId=10201
+Host: api.ntoklo.com
+Authorization: NTOKLO YzZkYmI2ZGUtYTNiYS00NWQ5LThjOWMtODZiZDBhNzljZjM5:2fa162cb5309764f5efe30fc007684bf29615a9b
+```
+
+## Client-side authentication
+nToklo also supports client-side requests via Javascript.
+
+In order to authenticate your client-side request you must specify your **API key** via request parameter. Here’s an example of making a client-side request using jQuery:
+
+```
+$.ajax({
+ type: "GET",
+ dataType: "json",
+ url: "https://api.ntoklo.com/recommendation"
+ + "?client_key=YzZkYmI2ZGUtYTNiYS00NWQ5LThjOWMtODZiZDBhNzljZjM5"
+ + "&userId=112&productId=10201"
+}).done(function(data) {
+ console.log("Response: " + JSON.stringify(data));
+});
+```
Oops, something went wrong.

0 comments on commit 5939840

Please sign in to comment.