diff --git a/_source/_layouts/default.haml b/_source/_layouts/default.haml index 39839ba..2c73e3b 100644 --- a/_source/_layouts/default.haml +++ b/_source/_layouts/default.haml @@ -81,6 +81,10 @@ %a{href: '/channel.html'} Channel %li %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/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/authentication.haml b/_source/authentication.haml index 0649253..76e927a 100644 --- a/_source/authentication.haml +++ b/_source/authentication.haml @@ -4,17 +4,17 @@ 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 and it will be used for all subsequent API calls to send data to Trak.io. %code.javascript :escaped @@ -24,7 +24,9 @@ title: Authentication %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'. + + %h4 Sending data %code.bash :escaped @@ -32,7 +34,17 @@ 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. + %h4 Retrieving data + + %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. + + %h4 Sending data %code.bash :escaped @@ -40,5 +52,13 @@ title: Authentication --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 \ + --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. diff --git a/_source/background_processing.haml b/_source/background_processing.haml index c144582..3283d7a 100644 --- a/_source/background_processing.haml +++ b/_source/background_processing.haml @@ -5,14 +5,15 @@ 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. 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 +21,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 relevant error codes when the request is made. %p @@ -31,7 +32,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" 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 87aeb72..c863a68 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 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 9534cac..bbb1e17 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 @@ -20,8 +22,10 @@ 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 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 @@ -52,7 +56,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 @@ -64,12 +68,35 @@ 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 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. + %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`. +%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" }}}' + --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/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/import.haml b/_source/import.haml new file mode 100644 index 0000000..ba42426 --- /dev/null +++ b/_source/import.haml @@ -0,0 +1,118 @@ +--- +title: Import +--- + +%h2 Import + +%p Import is how you record batches of events performed by people or companies. + +%p.note Batches greater than 2500 event objects will be rejected and invalid event objects will not be processed. + +#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: { + "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 + + %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/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/ruby.haml b/_source/ruby.haml index 9aed5b2..0363ee7 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 @@ -72,9 +76,18 @@ 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 + %li + %a{href: '/import.html#ruby'} Trakio.import + \- Coming Soon! + + %p The following methods are available to retrieve data from Trak.io: + + %ul %li - %a{href: '/page_view.html#ruby'} trakio.page_view + %a{href: '/score.html#ruby'} Trakio.score %p You can also use the following to alter your initial configuration: diff --git a/_source/score.haml b/_source/score.haml new file mode 100644 index 0000000..19d09dd --- /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 60 day 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', { api_secret_key: 'my_api_secret_key' } + 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 key='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 + } + } 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