From 79b750b9b254781cb435043b77bf707e2a9a51c4 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Mon, 6 Jul 2015 19:31:41 -0700 Subject: [PATCH 01/14] add score to menu layouts --- _source/_layouts/default.haml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_source/_layouts/default.haml b/_source/_layouts/default.haml index 39839ba..2db926e 100644 --- a/_source/_layouts/default.haml +++ b/_source/_layouts/default.haml @@ -81,6 +81,8 @@ %a{href: '/channel.html'} Channel %li %a{href: '/sign_out.html'} Sign Out + %li + %a{href: '/score.html'} Score %li.nav-header Notes on From 6bbd2ffbbfc368b59bd9593050c4e29c7abe298b Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Mon, 6 Jul 2015 19:32:40 -0700 Subject: [PATCH 02/14] update http page --- _source/http.haml | 44 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/_source/http.haml b/_source/http.haml index 9534cac..ff46789 100644 --- a/_source/http.haml +++ b/_source/http.haml @@ -6,11 +6,13 @@ title: HTTP API Introduction %p :markdown - The Trak.io HTTP API endpoint is at `https://api.trak.io/v1/` and supports three actions all of which are avaliable with `POST` and `GET` requests. + The Trak.io HTTP API endpoint is at `https://api.trak.io/v1/`. %p.note The HTTP API supports both HTTP and HTTPS, however we strongly recommend you only use HTTPS when connecting. All Trak.io's API libraries use HTTPS. +%h3 Sending data to Trak.io + %ul %li %a{href: '/identify.html#http'} POST\GET https://api.trak.io/v1/identify @@ -21,7 +23,7 @@ title: HTTP API Introduction %li %a{href: '/annotate.html#http'} POST\GET https://api.trak.io/v1/annotate -%p Any request expects the following, as url parameters when sending a GET request or as form data when sending a POST request: +%p Any request to the endpoints listed abov expects the following, as url parameters when sending a GET request or as form data when sending a POST request: %table.table.spread %thead @@ -73,3 +75,41 @@ title: HTTP API Introduction $ curl https://api.trak.io/v1/track \ --header "Content-Type: application/json" \ --data '{"token":"YOUR_API_TOKEN", "data":{"distinct_id": 12346789, "event": "Page view", "channel": "Web site", "properties": { "title": "Matts Home Page" }, "context": { "time_zone": "GMT" }}}' + +%h3 Retrieving data from Trak.io + +%ul + %li + %a{href: '/score.html#http'} GET https://api.trak.io/v1/score + +%p Any request to the endpoints listed above expects the following as url parameters when sending a GET request: + +%table.table.spread + %thead + %tr + %th Parameter + %th Type + %th Default + %th Description + %tbody + %tr + %th key + %td String + %td + %em Required + %td Your API secret key can be found in your account settings and verifies your account for retrieving data. + %tr + %th callback + %td String + %td null + %td If you are making a JSONP ajax call you can provide a callback method that will wrap the returning data. Setting a callback will change the force_200 default from false to true. + %tr + %th force_200 + %td Boolean + %td 0, 1 if callback provided + %td You can force a 200 status code by setting force_200 to true, this is designed specifically so that if you are using JSONP and there is an error you can still recieve the data. + %tr + %th destination + %td String + %td null + %td If destination is set, after the request has been performed it will redirect to the destination, this is helpful for example, when you wish to track someone clicking a link. \ No newline at end of file From 6922dad242a447e08e66f9f1a1c17394e04f3b32 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Mon, 6 Jul 2015 19:34:49 -0700 Subject: [PATCH 03/14] fix spelling --- _source/http.haml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_source/http.haml b/_source/http.haml index ff46789..aff26be 100644 --- a/_source/http.haml +++ b/_source/http.haml @@ -23,7 +23,7 @@ title: HTTP API Introduction %li %a{href: '/annotate.html#http'} POST\GET https://api.trak.io/v1/annotate -%p Any request to the endpoints listed abov expects the following, as url parameters when sending a GET request or as form data when sending a POST request: +%p Any request to the endpoints listed above expects the following, as url parameters when sending a GET request or as form data when sending a POST request: %table.table.spread %thead From b0893e3b5c92e3a859d2fc2c9b4e552d6ef63fa2 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Mon, 6 Jul 2015 20:31:31 -0700 Subject: [PATCH 04/14] update authentication --- _source/authentication.haml | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/_source/authentication.haml b/_source/authentication.haml index 0649253..93d6561 100644 --- a/_source/authentication.haml +++ b/_source/authentication.haml @@ -4,27 +4,29 @@ title: Authentication %h2 Authentication -%p You authenticate to the Trak.io API by providing your API token in the request. You can find your API token in your account. +%p You authenticate to the Trak.io API by providing your API token or API secret key in the request. You can find your API token and API secret key in your account settings. %h3 Expired Trials -%p If you account doesn't have a paid subscription and is out of the 14 free trial (plus an additional 28 day grace period) your request will be rejected with a 402 error +%p If your account doesn't have a paid subscription and is out of the 14 day free trial (plus an additional 28 day grace period) your request will be rejected with a 402 error %div.for-javascript %h3.first JavaScript - %p When using the JavaScript library you just can set the your API token once and it will be used for all subsequent API calls. + %p When using the JavaScript library you just can set your API token or API secret key once and it will be used for all subsequent API calls. %code.javascript :escaped - trak.io.load("YOUR_API_TOKEN"); + trak.io.load("YOUR_API_TOKEN"); ***CHANGE THIS!!! HC*** + trak.io.load_token("YOUR_API_TOKEN"); + trak.io.load_key("YOUR_API_SECRET_KEY"); %div.for-http %h3.first HTTP - %p When accessing the HTTP end points directly you should send your API token with each request in a query parameter named 'token'. + %p When accessing the HTTP end points directly to send data you should send your API token with each request in a query parameter named 'token'. When retrieving data you should send your API secret key with each request in a query parameter named 'key'. %code.bash :escaped @@ -32,7 +34,13 @@ title: Authentication --data token='YOUR_API_TOKEN'\ --data data='{"distinct_id": "12346789", "properties": { "name": "Matthew Spence" }}' - %p You can also send your API token as a HTTP header if you like. + %code.bash + :escaped + $ curl https://api.trak.io/v1/score \ + --data key='YOUR_API_SECRET_KEY'\ + --data distinct_id='12346789' + + %p You can also send your API token or API secret key as a HTTP header if you like. %code.bash :escaped @@ -40,5 +48,11 @@ title: Authentication --header "X-Trakio-Token: YOUR_API_TOKEN" \ --data data='{"distinct_id": "12346789", "properties": { "name": "Matthew Spence" }}' + %code.bash + :escaped + $ curl https://api.trak.io/v1/score \ + --header "X-Trakio-Key: YOUR_API_SECRET_KEY" \ + --data distinct_id="12346789" + %p.note - Providing your token in the header X-Token is depreciated, but still supported for backwards compatibility. + Providing your token in the header X-Token or your key in the header X-Key is depreciated, but still supported for backwards compatibility. From 552bfc8532b8c733df32fde0836a0d66edfb8974 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Mon, 6 Jul 2015 20:43:52 -0700 Subject: [PATCH 05/14] update errors --- _source/errors.haml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/_source/errors.haml b/_source/errors.haml index 87aeb72..b3bea8a 100644 --- a/_source/errors.haml +++ b/_source/errors.haml @@ -11,6 +11,7 @@ title: Errors %li DataObjectInvalidBase64 - the encoded data object provided was missing or invalid url safe base64 %li DataObjectInvalidType - the data value provided was not an object %li InvalidToken - API token was either missing or invalid + %li InvalidKey - API secret key was either missing or invalid %li MissingParameter - you missed a required data parameter %li RouteNotFound - You requested an end point that doesn't exist %li PropertiesObjectInvalid - the properties object provided was invalid @@ -18,6 +19,8 @@ title: Errors %li RevenuePropertyInvalid - revenue property for an event was not a float, integer or string %li TrialExpired - your account's free trial (including an additional 28 day grace period) has expired %li InternalServiceError - any other error will raise this, it usual means we did something wrong instead of you + %li PersonNotFound - You provided a distinct_id that doesn't exist + %li CompanyNotFound - You provided a company_id that doesn't exist .for-http @@ -29,7 +32,7 @@ title: Errors %li 200 - OK, everything worked as expected. %li 202 - accepted, the request was accepted and stored for background processing but may be rejected later if it is invalid %li 400 - bad request, missing a required parameter, or incorrect format - %li 401 - unauthorized, missing or invalid API token + %li 401 - unauthorized, missing or invalid API token/secret key %li 402 - payment required, your account's free trial has expired (including a 28 day grace period) %li 404 - not found, the requested method or item doesn't exist %li 500, 502, 503, 504 - server errors, these are on us :( @@ -40,7 +43,7 @@ title: Errors :escaped { "status": "error", - "code": 401, # repeats the HTTP status code, usefull if using the force_200 argument + "code": 401, # repeats the HTTP status code, useful if using the force_200 argument "exception": "TrakioAPI::Exceptions::InvalidToken", # The exception class raised "message": "Missing or invalid API token.", # The message for the raised exception "details": "You must povide a valid API token, see http://docs.tra.io/authentication.html." # Additional details for the specific error @@ -50,11 +53,11 @@ title: Errors %h3.first JavaScript - %p When the JavaScript library encounters one of the above exceptions it will throw an equivilent JavaScript error. + %p When the JavaScript library encounters one of the above exceptions it will throw an equivalent JavaScript error. .for-ruby %h3.first Ruby - %p When the Ruby library recieves one of the above response exceptions it will raise an equivilent Ruby exception. + %p When the Ruby library recieves one of the above response exceptions it will raise an equivalent Ruby exception. From 1c8123876a21b522cedf869e61aa53a161883449 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Mon, 6 Jul 2015 22:23:50 -0700 Subject: [PATCH 06/14] update background_processing --- _source/background_processing.haml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_source/background_processing.haml b/_source/background_processing.haml index c144582..d9e1e46 100644 --- a/_source/background_processing.haml +++ b/_source/background_processing.haml @@ -5,14 +5,14 @@ title: Background Processing %h2 Background Processing %p - When the Trak.io API recieves a request it is not processed immediately. It is + Most Trak.io API requests are not processed immediately. It is validated and stored in a queue for processing by a background processor. Under normal conditions the background worker will process the request within a - second or two of being recieved. + second or two of being received. However, requests to retrieve data are not queued and are processed immediately. %p This ensures we can respond to API request as quickly as possible and adds a - layer of redundency that ensures we can continue to recieve and respond promptly to your + layer of redundency that ensures we can continue to receive and respond promptly to your API requests during periods of unusually high traffic or while we are having technical difficulties. @@ -20,7 +20,7 @@ title: Background Processing %p Before requests are queued for processing they are validated to predict any problems - that may arise during processing. This allows us to respond with the relavent error + that may arise during processing. This allows us to respond with the relevent error codes when the request is made. %p @@ -31,7 +31,7 @@ title: Background Processing %p.note Whilst we aim to have all of our services up all of the time, the realities of technlogy, means we need to pepare for having parts of our system unavailable. Having - our API up to recieve your data regardless of the status of our other systems + our API up to receive your data regardless of the status of our other systems is our number one priority. %h3 "The Benefit of the Doubt" From 5ff77b19be44f0ff94b6cb7cbfc44b38e45231d4 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Mon, 6 Jul 2015 22:27:59 -0700 Subject: [PATCH 07/14] fix spelling --- _source/background_processing.haml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_source/background_processing.haml b/_source/background_processing.haml index d9e1e46..5b21638 100644 --- a/_source/background_processing.haml +++ b/_source/background_processing.haml @@ -20,7 +20,7 @@ title: Background Processing %p Before requests are queued for processing they are validated to predict any problems - that may arise during processing. This allows us to respond with the relevent error + that may arise during processing. This allows us to respond with the relevant error codes when the request is made. %p From 17b6b7bf18805c5e691f0e41c35dfc1c4299b2f8 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Tue, 7 Jul 2015 15:26:59 -0700 Subject: [PATCH 08/14] add score.haml --- _source/score.haml | 119 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 _source/score.haml diff --git a/_source/score.haml b/_source/score.haml new file mode 100644 index 0000000..97ffec1 --- /dev/null +++ b/_source/score.haml @@ -0,0 +1,119 @@ +--- +title: Score +--- + +%h2 Score + +%p Score is how you retrieve the current Trak.io SuccessRank score and score history for a person or company. + +#javascript.for-javascript + + %h3.first JavaScript + + %p Since scores require an API secret key they are not supported by the JavaScript library. If you are building a JavaScript based client for trak.io and need to retrieve scores, please let us know and we'll work on adding it. + +#ruby.for-ruby + + %h3.first Ruby + + %p Retrieves a SuccessRank score and score history for a person with the specified distinct_id or company with the specified company_id. + + %code.ruby.spread + :preserve + Trakio.score distinct_id: 'tobie@trak.io' + } + + trakio = Trakio.new 'my_api_token', { distinct_id: 'tobie@trak.io', channel: 'web_app' } *** INCORRECT *** + trakio.score distinct_id: 'tobie@trak.io' + + %h4 Arguments + + %table.table.spread + %thead + %tr + %th Argument + %th Type + %th Default + %th Description + %tbody + %tr + %td distinct_id + %td String + %td + %em Required, unless company_id is provided + %td The distinct ID for the person you wish to retrieve a SuccessRank score for + %tr#ruby-arguments-company-id + %td company_id + %td String + %td + %em Required, unless distinct_id is provided + %td The company ID for the company you wish to retrieve a SuccessRank score for + + %h4 Return Value + + %p The return value of score is a Ruby Hash similar to the one below. + + %code.ruby.spread + :preserve + { + "status": "success", + "score": 333, + "score_history": { + "2015-06-09": 333, + "2015-06-08": 333, + "2015-06-07": 333 + } + } + +#http.for-http + + %h3.first HTTP + + %p A raw HTTP call to api.trak.io/v1/score has certain requirements and options as outlined in the introduction to the HTTP API. In addition data specific to the track action should be sent in the data parameter as a JSON string. + + %code.bash.spread + :escaped + $ curl -v -XPOST \ + --data token='YOUR_API_SECRET_KEY' \ + --data distinct_id='12346789' \ + https://api.trak.io/v1/score + + %h4 Data Object + + %table.table.spread + %thead + %tr + %th Property + %th Type + %th Default + %th Description + %tbody + %tr#http-argument-distinct-id + %th distinct_id + %td String + %td + %em Required, unless company_id is provided + %td The distinct ID of the person you wish to retrieve a SuccessRank score for. + %tr#http-argument-company-id + %th company_id + %td String + %td + %em Required, unless distinct_id is provided + %td The company ID of the company you wish to retrieve a SuccessRank score for. + +#return + %h3 Return Value + + %p When score returns you will receive an object with the following structure. + + %code.json + :escaped + { + "status": "success", + "score": 333, + "score_history": { + "2015-06-09": 333, + "2015-06-08": 333, + "2015-06-07": 333 + } + } From 2ea620ef4c16794cc4a02ac14740f2d4eadd0fda Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Tue, 7 Jul 2015 15:27:47 -0700 Subject: [PATCH 09/14] update JS / callback related stuff for score --- _source/authentication.haml | 14 ++++++++---- _source/background_processing.haml | 3 ++- _source/http.haml | 35 +++++++++--------------------- _source/ruby.haml | 10 +++++++-- 4 files changed, 30 insertions(+), 32 deletions(-) diff --git a/_source/authentication.haml b/_source/authentication.haml index 93d6561..76e927a 100644 --- a/_source/authentication.haml +++ b/_source/authentication.haml @@ -14,13 +14,11 @@ title: Authentication %h3.first JavaScript - %p When using the JavaScript library you just can set your API token or API secret key once and it will be used for all subsequent API calls. + %p When using the JavaScript library you just can set your API token and it will be used for all subsequent API calls to send data to Trak.io. %code.javascript :escaped - trak.io.load("YOUR_API_TOKEN"); ***CHANGE THIS!!! HC*** - trak.io.load_token("YOUR_API_TOKEN"); - trak.io.load_key("YOUR_API_SECRET_KEY"); + trak.io.load("YOUR_API_TOKEN"); %div.for-http @@ -28,12 +26,16 @@ title: Authentication %p When accessing the HTTP end points directly to send data you should send your API token with each request in a query parameter named 'token'. When retrieving data you should send your API secret key with each request in a query parameter named 'key'. + %h4 Sending data + %code.bash :escaped $ curl https://api.trak.io/v1/identify \ --data token='YOUR_API_TOKEN'\ --data data='{"distinct_id": "12346789", "properties": { "name": "Matthew Spence" }}' + %h4 Retrieving data + %code.bash :escaped $ curl https://api.trak.io/v1/score \ @@ -42,12 +44,16 @@ title: Authentication %p You can also send your API token or API secret key as a HTTP header if you like. + %h4 Sending data + %code.bash :escaped $ curl https://api.trak.io/v1/identify \ --header "X-Trakio-Token: YOUR_API_TOKEN" \ --data data='{"distinct_id": "12346789", "properties": { "name": "Matthew Spence" }}' + %h4 Retrieving data + %code.bash :escaped $ curl https://api.trak.io/v1/score \ diff --git a/_source/background_processing.haml b/_source/background_processing.haml index 5b21638..3283d7a 100644 --- a/_source/background_processing.haml +++ b/_source/background_processing.haml @@ -8,7 +8,8 @@ title: Background Processing Most Trak.io API requests are not processed immediately. It is validated and stored in a queue for processing by a background processor. Under normal conditions the background worker will process the request within a - second or two of being received. However, requests to retrieve data are not queued and are processed immediately. + second or two of being received. Requests to retrieve data are not queued and are + processed immediately. %p This ensures we can respond to API request as quickly as possible and adds a diff --git a/_source/http.haml b/_source/http.haml index aff26be..cb351c9 100644 --- a/_source/http.haml +++ b/_source/http.haml @@ -66,16 +66,6 @@ title: HTTP API Introduction %td null %td If destination is set, after the request has been performed it will redirect to the destination, this is helpful for example, when you wish to track someone clicking a link. -%h3#full-json Sending Requests As JSON - -%p You can send the above request parameters as encoded JSON, as apposed to GET parameters or POST form data, by setting your `Content-Type` request HTTP header to `application/json`. - -%code.bash.spread - :escaped - $ curl https://api.trak.io/v1/track \ - --header "Content-Type: application/json" \ - --data '{"token":"YOUR_API_TOKEN", "data":{"distinct_id": 12346789, "event": "Page view", "channel": "Web site", "properties": { "title": "Matts Home Page" }, "context": { "time_zone": "GMT" }}}' - %h3 Retrieving data from Trak.io %ul @@ -98,18 +88,13 @@ title: HTTP API Introduction %td %em Required %td Your API secret key can be found in your account settings and verifies your account for retrieving data. - %tr - %th callback - %td String - %td null - %td If you are making a JSONP ajax call you can provide a callback method that will wrap the returning data. Setting a callback will change the force_200 default from false to true. - %tr - %th force_200 - %td Boolean - %td 0, 1 if callback provided - %td You can force a 200 status code by setting force_200 to true, this is designed specifically so that if you are using JSONP and there is an error you can still recieve the data. - %tr - %th destination - %td String - %td null - %td If destination is set, after the request has been performed it will redirect to the destination, this is helpful for example, when you wish to track someone clicking a link. \ No newline at end of file + +%h3#full-json Sending Requests As JSON + +%p You can send the request parameters as encoded JSON, as apposed to GET parameters or POST form data, by setting your `Content-Type` request HTTP header to `application/json`. + +%code.bash.spread + :escaped + $ curl https://api.trak.io/v1/track \ + --header "Content-Type: application/json" \ + --data '{"token":"YOUR_API_TOKEN", "data":{"distinct_id": 12346789, "event": "Page view", "channel": "Web site", "properties": { "title": "Matts Home Page" }, "context": { "time_zone": "GMT" }}}' \ No newline at end of file diff --git a/_source/ruby.haml b/_source/ruby.haml index 9aed5b2..46f7fbf 100644 --- a/_source/ruby.haml +++ b/_source/ruby.haml @@ -72,9 +72,15 @@ title: Ruby API Introduction %li %a{href: '/track.html#ruby'} Trakio.track %li - %a{href: '/annotate.html#ruby'} trakio.annotate + %a{href: '/annotate.html#ruby'} Trakio.annotate %li - %a{href: '/page_view.html#ruby'} trakio.page_view + %a{href: '/page_view.html#ruby'} Trakio.page_view + + %p The following methods are available to retrieve data from Trak.io: + + %ul + %li + %a{href: '/score.html#ruby'} Trakio.score %p You can also use the following to alter your initial configuration: From de31d9bcf655e1e66dfca7f1e984e74c6b170b48 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Tue, 7 Jul 2015 15:38:11 -0700 Subject: [PATCH 10/14] add 60 day score history info to score --- _source/score.haml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_source/score.haml b/_source/score.haml index 97ffec1..52b4340 100644 --- a/_source/score.haml +++ b/_source/score.haml @@ -16,7 +16,7 @@ title: Score %h3.first Ruby - %p Retrieves a SuccessRank score and score history for a person with the specified distinct_id or company with the specified company_id. + %p Retrieves a SuccessRank score and 60 day score history for a person with the specified distinct_id or company with the specified company_id. %code.ruby.spread :preserve From 292fa57a4505927d87f1d2da0715d0643f99cd06 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Tue, 7 Jul 2015 15:45:00 -0700 Subject: [PATCH 11/14] fix receive spelling --- _source/alias.haml | 2 +- _source/annotate.haml | 2 +- _source/company.haml | 2 +- _source/errors.haml | 2 +- _source/http.haml | 2 +- _source/identify.haml | 2 +- _source/javascript/automagic.haml | 2 +- _source/track.haml | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/_source/alias.haml b/_source/alias.haml index 4d36b1f..a46b8e0 100644 --- a/_source/alias.haml +++ b/_source/alias.haml @@ -168,7 +168,7 @@ title: Alias %h3 Return Value - %p When alias returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. + %p When alias returns you will receive an object with the following structure. This response means your request was successfully received and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. %code.json.spread :escaped diff --git a/_source/annotate.haml b/_source/annotate.haml index edea85a..1b4ff26 100644 --- a/_source/annotate.haml +++ b/_source/annotate.haml @@ -102,7 +102,7 @@ title: Annotate %h3#return Return Value -%p When annotate returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. +%p When annotate returns you will receive an object with the following structure. This response means your request was successfully received and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. %code.json :escaped diff --git a/_source/company.haml b/_source/company.haml index 6dd7a9c..ccb3070 100644 --- a/_source/company.haml +++ b/_source/company.haml @@ -218,7 +218,7 @@ title: Company #return %h3 Return Value - %p When company returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. + %p When company returns you will receive an object with the following structure. This response means your request was successfully received and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. %code.json.spread :escaped diff --git a/_source/errors.haml b/_source/errors.haml index b3bea8a..c863a68 100644 --- a/_source/errors.haml +++ b/_source/errors.haml @@ -59,5 +59,5 @@ title: Errors %h3.first Ruby - %p When the Ruby library recieves one of the above response exceptions it will raise an equivalent Ruby exception. + %p When the Ruby library receives one of the above response exceptions it will raise an equivalent Ruby exception. diff --git a/_source/http.haml b/_source/http.haml index cb351c9..5a4f5b7 100644 --- a/_source/http.haml +++ b/_source/http.haml @@ -54,7 +54,7 @@ title: HTTP API Introduction %th force_200 %td Boolean %td 0, 1 if callback provided - %td You can force a 200 status code by setting force_200 to true, this is designed specifically so that if you are using JSONP and there is an error you can still recieve the data. + %td You can force a 200 status code by setting force_200 to true, this is designed specifically so that if you are using JSONP and there is an error you can still receive the data. %tr %th img %td Boolean diff --git a/_source/identify.haml b/_source/identify.haml index f82809a..783ca7c 100644 --- a/_source/identify.haml +++ b/_source/identify.haml @@ -261,7 +261,7 @@ title: Identify #return %h3 Return Value - %p When identify returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. + %p When identify returns you will receive an object with the following structure. This response means your request was successfully received and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. %code.json.spread :escaped diff --git a/_source/javascript/automagic.haml b/_source/javascript/automagic.haml index 33637dd..ebf160e 100644 --- a/_source/javascript/automagic.haml +++ b/_source/javascript/automagic.haml @@ -148,7 +148,7 @@ title: "JavaScript API: AutoMagic" A callback to determine if trak.io.identify() should be called. Returning true will fire the trak.io.identify() function, returning false will not. The function is called from the scope of (ie this is equal to) trak.io.automagic. - It recieves the element that triggered the event as its first argument and the event object as the second. + It receives the element that triggered the event as its first argument and the event object as the second. #track diff --git a/_source/track.haml b/_source/track.haml index a44441a..211709e 100644 --- a/_source/track.haml +++ b/_source/track.haml @@ -327,7 +327,7 @@ title: Track #return %h3 Return Value - %p When track returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. + %p When track returns you will receive an object with the following structure. This response means your request was successfully received and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. %code.json :escaped From c5e82db6da3e033a4f17bd66c0d2b62a12a7dee6 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Fri, 10 Jul 2015 14:29:53 -0700 Subject: [PATCH 12/14] add api_secret_key updates --- _source/ruby.haml | 4 ++++ _source/score.haml | 8 ++++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/_source/ruby.haml b/_source/ruby.haml index 46f7fbf..f2e977d 100644 --- a/_source/ruby.haml +++ b/_source/ruby.haml @@ -45,6 +45,10 @@ title: Ruby API Introduction %th Type %th Description %tbody + %tr + %td api_secret_key + %td String + %td The api_secret_key is required if you would like to retrieve data. You can find your API secret key in your account settings. %tr %td distinct_id %td String diff --git a/_source/score.haml b/_source/score.haml index 52b4340..19d09dd 100644 --- a/_source/score.haml +++ b/_source/score.haml @@ -4,7 +4,7 @@ title: Score %h2 Score -%p Score is how you retrieve the current Trak.io SuccessRank score and score history for a person or company. +%p Score is how you retrieve the current Trak.io SuccessRank score and 60 day score history for a person or company. #javascript.for-javascript @@ -16,14 +16,14 @@ title: Score %h3.first Ruby - %p Retrieves a SuccessRank score and 60 day score history for a person with the specified distinct_id or company with the specified company_id. + %p Retrieves a SuccessRank score and score history for a person with the specified distinct_id or company with the specified company_id. %code.ruby.spread :preserve Trakio.score distinct_id: 'tobie@trak.io' } - trakio = Trakio.new 'my_api_token', { distinct_id: 'tobie@trak.io', channel: 'web_app' } *** INCORRECT *** + trakio = Trakio.new 'my_api_token', { api_secret_key: 'my_api_secret_key' } trakio.score distinct_id: 'tobie@trak.io' %h4 Arguments @@ -74,7 +74,7 @@ title: Score %code.bash.spread :escaped $ curl -v -XPOST \ - --data token='YOUR_API_SECRET_KEY' \ + --data key='YOUR_API_SECRET_KEY' \ --data distinct_id='12346789' \ https://api.trak.io/v1/score From 44c5ba5e0b6d075bf463e3ee65073e46e8d543e3 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Wed, 15 Jul 2015 16:55:16 -0700 Subject: [PATCH 13/14] first draft --- _source/_layouts/default.haml | 2 + _source/http.haml | 2 + _source/import.haml | 107 ++++++++++++++++++++++++++++++++++ _source/ruby.haml | 2 + 4 files changed, 113 insertions(+) create mode 100644 _source/import.haml diff --git a/_source/_layouts/default.haml b/_source/_layouts/default.haml index 2db926e..2c73e3b 100644 --- a/_source/_layouts/default.haml +++ b/_source/_layouts/default.haml @@ -83,6 +83,8 @@ %a{href: '/sign_out.html'} Sign Out %li %a{href: '/score.html'} Score + %li + %a{href: '/import.html'} Import %li.nav-header Notes on diff --git a/_source/http.haml b/_source/http.haml index 5a4f5b7..bbb1e17 100644 --- a/_source/http.haml +++ b/_source/http.haml @@ -22,6 +22,8 @@ title: HTTP API Introduction %a{href: '/track.html#http'} POST\GET https://api.trak.io/v1/track %li %a{href: '/annotate.html#http'} POST\GET https://api.trak.io/v1/annotate + %li + %a{href: '/import.html#http'} POST\GET https://api.trak.io/v1/import %p Any request to the endpoints listed above expects the following, as url parameters when sending a GET request or as form data when sending a POST request: diff --git a/_source/import.haml b/_source/import.haml new file mode 100644 index 0000000..b267d17 --- /dev/null +++ b/_source/import.haml @@ -0,0 +1,107 @@ +--- +title: Import +--- + +%h2 Import + +%p Import is how you load batches of events. + +%p.note 2500 limit. + +%p.note Invalid event objects will not be processed. No errors are thrown. + +#javascript.for-javascript + + %h3.first JavaScript + + %p Coming soon! + +#ruby.for-ruby + + %h3.first Ruby + + %p Coming soon! + +#http.for-http + + %h3.first HTTP + + %p A raw HTTP call to api.trak.io/v1/import has certain requirements and options as outlined in the introduction to the HTTP API. In addition data specific to the import action should be sent in the data parameter as a JSON string. + + %code.bash.spread + :escaped + $ curl -v -XPOST \ + --data token=YOUR_API_TOKEN \ + --data data='{events: {"distinct_id": "12346789", "company_id": "acme_ltd", "event": "Page view", "channel": "Web site", "properties": {}, "context": { "time_zone": "GMT" }}}' \ + https://api.trak.io/v1/import + + %h4 Data Object + + %table.table.spread + %thead + %tr + %th Property + %th Type + %th Default + %th Description + %tbody + %tr#http-argument-distinct-id + %th events + %td Array + %td + %em Required + %td A list of event objects you wish to import. + + %h4 Event Object + + %table.table.spread + %thead + %tr + %th Property + %th Type + %th Default + %th Description + %tbody + %tr#http-argument-distinct-id + %th distinct_id + %td String + %td + %em Required, unless company_id is provided + %td The distinct ID of the person you wish to register this event against. + %tr#http-argument-company-id + %th company_id + %td String + %td + %em Required, unless distinct_id is provided + %td The company ID of the company you wish to register this event against. + %tr + %th event + %td String + %td + %em Required + %td The key for this event, this value will be standardized server side. + %tr + %th channel + %td String + %td web_site + %td The channel this event occurred in. + %tr + %th properties + %td Object + %td {} + %td A set of key value properties that help describe the event. + %tr#time + %th time + %td String (ISO 8601) + %td + %em Now + %td The time that this event occurred, the time should be a string formatted in ISO 8601. + +#return + %h3 Return Value + + %p When track returns you will receive an object with the following structure. This response means your request was successfully received and queued for proccessing. Under normal conditions this will happen asyncronously within a second or two. + + %code.json + :escaped + { "status": "success" } diff --git a/_source/ruby.haml b/_source/ruby.haml index f2e977d..1407b97 100644 --- a/_source/ruby.haml +++ b/_source/ruby.haml @@ -79,6 +79,8 @@ title: Ruby API Introduction %a{href: '/annotate.html#ruby'} Trakio.annotate %li %a{href: '/page_view.html#ruby'} Trakio.page_view + %li + %a{href: '/import.html#ruby'} Trakio.import - Coming Soon! %p The following methods are available to retrieve data from Trak.io: From 724ec0254b579a3608ecd9c28c4d17ca132563d0 Mon Sep 17 00:00:00 2001 From: Herine Chin Date: Mon, 20 Jul 2015 18:47:34 -0700 Subject: [PATCH 14/14] update import doc --- _source/import.haml | 21 ++++++++++++++++----- _source/ruby.haml | 3 ++- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/_source/import.haml b/_source/import.haml index b267d17..ba42426 100644 --- a/_source/import.haml +++ b/_source/import.haml @@ -4,11 +4,9 @@ title: Import %h2 Import -%p Import is how you load batches of events. +%p Import is how you record batches of events performed by people or companies. -%p.note 2500 limit. - -%p.note Invalid event objects will not be processed. No errors are thrown. +%p.note Batches greater than 2500 event objects will be rejected and invalid event objects will not be processed. #javascript.for-javascript @@ -32,7 +30,20 @@ title: Import :escaped $ curl -v -XPOST \ --data token=YOUR_API_TOKEN \ - --data data='{events: {"distinct_id": "12346789", "company_id": "acme_ltd", "event": "Page view", "channel": "Web site", "properties": {}, "context": { "time_zone": "GMT" }}}' \ + --data data='{ + events: { + "event": "Page view", + "distinct_id": "12346789" + "channel": "Web site", + "properties": {}, + "context": { "time_zone": "GMT" } + },{ + "event": "Page view", + "company_id": "987654321", + "channel": "Web site", + "properties": {}, + "context": { "time_zone": "GMT" } + }' \ https://api.trak.io/v1/import %h4 Data Object diff --git a/_source/ruby.haml b/_source/ruby.haml index 1407b97..0363ee7 100644 --- a/_source/ruby.haml +++ b/_source/ruby.haml @@ -80,7 +80,8 @@ title: Ruby API Introduction %li %a{href: '/page_view.html#ruby'} Trakio.page_view %li - %a{href: '/import.html#ruby'} Trakio.import - Coming Soon! + %a{href: '/import.html#ruby'} Trakio.import + \- Coming Soon! %p The following methods are available to retrieve data from Trak.io: