README.md in keen-0.8.7 vs README.md in keen-0.8.8

- old
+ new

@@ -1,11 +1,11 @@ # Keen IO Official Ruby Client Library [![Build Status](https://secure.travis-ci.org/keenlabs/keen-gem.png?branch=master)](http://travis-ci.org/keenlabs/keen-gem) [![Code Climate](https://codeclimate.com/github/keenlabs/keen-gem.png)](https://codeclimate.com/github/keenlabs/keen-gem) [![Gem Version](https://badge.fury.io/rb/keen.svg)](http://badge.fury.io/rb/keen) -keen-gem is the official Ruby Client for the [Keen IO](https://keen.io/) API. The +keen-gem is the official Ruby Client for the [Keen IO](https://keen.io/?s=gh-gem) API. The Keen IO API lets developers build analytics features directly into their apps. ### Installation Add to your Gemfile: @@ -23,18 +23,18 @@ * jRuby (except for asynchronous methods - no TLS support for EM on jRuby) ### Usage Before making any API calls, you must supply keen-gem with a Project ID and one or more authentication keys. -(If you need a Keen IO account, [sign up here](https://keen.io/signup) - it's free.) +(If you need a Keen IO account, [sign up here](https://keen.io/signup?s=gh-gem) - it's free.) Setting a write key is required for publishing events. Setting a read key is required for running queries. Setting a master key is required for performing deletes. You can find keys for all of your projects -on [keen.io](https://keen.io). +on [keen.io](https://keen.io?s=gh-gem). The recommended way to set keys is via the environment. The keys you can set are -`KEEN_PROJECT_ID`, `KEEN_WRITE_KEY`, `KEEN_READ_KEY`, and `KEEN_MASTER_KEY`. +`KEEN_PROJECT_ID`, `KEEN_WRITE_KEY`, `KEEN_READ_KEY` and `KEEN_MASTER_KEY`. You only need to specify the keys that correspond to the API calls you'll be performing. If you're using [foreman](http://ddollar.github.com/foreman/), add this to your `.env` file: KEEN_PROJECT_ID=aaaaaaaaaaaaaaa KEEN_MASTER_KEY=xxxxxxxxxxxxxxx @@ -56,11 +56,11 @@ ```ruby Keen.publish(:sign_ups, { :username => "lloyd", :referred_by => "harry" }) ``` This will publish an event to the `sign_ups` collection with the `username` and `referred_by` properties set. -The event properties can be any valid Ruby hash. Nested properties are allowed. Lists of objects are also allowed, but not recommended because they can be difficult to query over. See alternatives to lists of objects [here](http://stackoverflow.com/questions/24620330/nested-json-objects-in-keen-io). You can learn more about data modeling with Keen IO with the [Data Modeling Guide](https://keen.io/docs/event-data-modeling/event-data-intro/). +The event properties can be any valid Ruby hash. Nested properties are allowed. Lists of objects are also allowed, but not recommended because they can be difficult to query over. See alternatives to lists of objects [here](http://stackoverflow.com/questions/24620330/nested-json-objects-in-keen-io). You can learn more about data modeling with Keen IO with the [Data Modeling Guide](https://keen.io/docs/event-data-modeling/event-data-intro/?s=gh-gem). Protip: Marshalling gems like [Blockhead](https://github.com/vinniefranco/blockhead) make converting structs or objects to hashes easier. The event collection need not exist in advance. If it doesn't exist, Keen IO will create it on the first request. @@ -104,11 +104,11 @@ This will schedule the network call into the event loop and allow your request thread to resume processing immediately. ### Running queries -The Keen IO API provides rich querying capabilities against your event data set. For more information, see the [Data Analysis API Guide](https://keen.io/docs/data-analysis/). +The Keen IO API provides rich querying capabilities against your event data set. For more information, see the [Data Analysis API Guide](https://keen.io/docs/data-analysis/?s=gh-gem). Running queries requires that `KEEN_READ_KEY` is set. Here are some examples of querying with keen-gem. Let's assume you've added some events to the "purchases" collection. @@ -119,31 +119,35 @@ Keen.maximum("purchases", :target_property => "price") # => 100 Keen.average("purchases", :target_property => "price") # => 60 Keen.median("purchases", :target_property => "price") # => 60 Keen.percentile("purchases", :target_property => "price", :percentile => 90) # => 100 -Keen.sum("purchases", :target_property => "price", :group_by => "item.id") # => [{ "item.id": 123, "result": 240 }, { ... }] +Keen.sum("purchases", :target_property => "price", :group_by => "item.id") # => [{ "item.id": 123, "result": 240 }] +Keen.count("purchases", :timeframe => "today", :filters => [{ + "property_name" => "referred_by", + "operator" => "eq", + "property_value" => "harry" + }]) # => 2 Keen.count_unique("purchases", :target_property => "username") # => 3 Keen.select_unique("purchases", :target_property => "username") # => ["Bob", "Linda", "Travis"] -Keen.extraction("purchases") # => [{ "price" => 20, ... }, { ... }] +Keen.extraction("purchases") # => [{ "keen" => { "timestamp" => "2014-01-01T00:00:00Z" }, "price" => 20 }] -Keen.funnel(:steps => [ - { :actor_property => "username", :event_collection => "purchases" }, - { :actor_property => "username", :event_collection => "referrals" }, - { ... }]) # => [20, 15 ...] +Keen.funnel(:steps => [{ + :actor_property => "username", :event_collection => "purchases" }, { + :actor_property => "username", :event_collection => "referrals" }]) # => [20, 15] Keen.multi_analysis("purchases", analyses: { :gross => { :analysis_type => "sum", :target_property => "price" }, :customers => { :analysis_type => "count_unique", :target_property => "username" } }, - :timeframe => 'today', :group_by => "item.id") # => [{"item.id"=>2, "gross"=>314.49, "customers"=> 8}, { ... }] + :timeframe => 'today', :group_by => "item.id") # => [{ "item.id" => 2, "gross" => 314.49, "customers" => 8 } }] ``` Many of these queries can be performed with group by, filters, series and intervals. The response is returned as a Ruby Hash or Array. -Detailed information on available parameters for each API resource can be found on the [API Technical Reference](https://keen.io/docs/api/reference/). +Detailed information on available parameters for each API resource can be found on the [API Technical Reference](https://keen.io/docs/api/reference/?s=gh-gem). ##### The Query Method You can also specify the analysis type as a parameter to a method called `query`: @@ -185,11 +189,11 @@ Getting the list of event collections requires that the `KEEN_MASTER_KEY` is set. ### Deleting events -The Keen IO API allows you to [delete events](https://keen.io/docs/maintenance/#deleting-event-collections) +The Keen IO API allows you to [delete events](https://keen.io/docs/maintenance/#deleting-event-collections?s=gh-gem) from event collections, optionally supplying a filter to narrow the scope of what you would like to delete. Deleting events requires that the `KEEN_MASTER_KEY` is set. ```ruby @@ -206,11 +210,11 @@ ### Other code examples #### Overwriting event timestamps -Two time-related properties are included in your event automatically. The properties “keen.timestamp” and “keen.created_at” are set at the time your event is recorded. You have the ability to overwrite the keen.timestamp property. This could be useful, for example, if you are backfilling historical data. Be sure to use [ISO-8601 Format](https://keen.io/docs/event-data-modeling/event-data-intro/#iso-8601-format). +Two time-related properties are included in your event automatically. The properties “keen.timestamp” and “keen.created_at” are set at the time your event is recorded. You have the ability to overwrite the keen.timestamp property. This could be useful, for example, if you are backfilling historical data. Be sure to use [ISO-8601 Format](https://keen.io/docs/event-data-modeling/event-data-intro/#iso-8601-format?s=gh-gem). Keen stores all date and time information in UTC! ```ruby Keen.publish(:sign_ups, { @@ -264,19 +268,21 @@ ```ruby Keen.project_id = 'xxxxxxxxxxxxxxx' Keen.write_key = 'yyyyyyyyyyyyyyy' Keen.read_key = 'zzzzzzzzzzzzzzz' Keen.master_key = 'aaaaaaaaaaaaaaa' +Keen.read_timeoout = 60 ``` You can also configure unique client instances as follows: ```ruby keen = Keen::Client.new(:project_id => 'xxxxxxxxxxxxxxx', :write_key => 'yyyyyyyyyyyyyyy', :read_key => 'zzzzzzzzzzzzzzz', - :master_key => 'aaaaaaaaaaaaaaa') + :master_key => 'aaaaaaaaaaaaaaa', + :read_timeout => 60) ``` #### em-synchrony keen-gem can be used with [em-synchrony](https://github.com/igrigorik/em-synchrony). @@ -297,26 +303,26 @@ Keen.write_key = 'yyyyyy'; Keen.beacon_url("sign_ups", :recipient => "foo@foo.com") # => "https://api.keen.io/3.0/projects/xxxxxx/events/email_opens?api_key=yyyyyy&data=eyJyZWNpcGllbnQiOiJmb29AZm9vLmNvbSJ9" ``` -To track email opens, simply add an image to your email template that points to this URL. For further information on how to do this, see the [image beacon documentation](https://keen.io/docs/data-collection/image-beacon/). +To track email opens, simply add an image to your email template that points to this URL. For further information on how to do this, see the [image beacon documentation](https://keen.io/docs/data-collection/image-beacon/?s=gh-gem). #### Redirect URLs Redirect URLs are just like image beacon URLs with the addition of a `redirect` query parameter. This parameter is used to issue a redirect to a certain URL after an event is recorded. -``` +``` ruby Keen.redirect_url("sign_ups", { :recipient => "foo@foo.com" }, "http://foo.com") # => "https://api.keen.io/3.0/projects/xxxxxx/events/email_opens?api_key=yyyyyy&data=eyJyZWNpcGllbnQiOiJmb29AZm9vLmNvbSJ9&redirect=http://foo.com" ``` -This is helpful for tracking email clickthroughs. See the [redirect documentation](https://keen.io/docs/data-collection/redirect/) for further information. +This is helpful for tracking email clickthroughs. See the [redirect documentation](https://keen.io/docs/data-collection/redirect/?s=gh-gem) for further information. #### Generating scoped keys -A [scoped key](https://keen.io/docs/security/#scoped-key) is a string, generated with your API Key, that represents some encrypted authentication and query options. +A [scoped key](https://keen.io/docs/security/#scoped-key?s=gh-gem) is a string, generated with your API Key, that represents some encrypted authentication and query options. Use them to control what data queries have access to. ``` ruby # "my-api-key" should be your MASTER API key scoped_key = Keen::ScopedKey.new("my-api-key", { "filters" => [{ @@ -326,10 +332,25 @@ }]}).encrypt! # "4d1982fe601b359a5cab7ac7845d3bf27026936cdbf8ce0ab4ebcb6930d6cf7f139e..." ``` You can use the scoped key created in Ruby for API requests from any client. Scoped keys are commonly used in JavaScript, where credentials are visible and need to be protected. +### Additional options + +##### HTTP Read Timeout + +The default `Net:HTTP` timeout is 60 seconds. That's usually enough, but if you're querying over a large collection you may need to increase it. The timeout on the API side is 300 seconds, so that's as far as you'd want to go. You can configure a read timeout (in seconds) by setting a `KEEN_READ_TIMEOUT` environment variable, or by passing in a `read_timeout` option to the client constructor as follows: + +``` +keen = Keen::Client.new(:read_timeout => 300) +``` + +##### HTTP Proxy + +You can set the `KEEN_PROXY_TYPE` and `KEEN_PROXY_URL` environment variables to enable HTTP proxying. `KEEN_PROXY_TYPE` should most likely be set to `socks5`. You can also configure this on client instances by passing in `proxy_type` and `proxy_url` keys. + + ### Troubleshooting ##### EventMachine If you run into `Keen::Error: Keen IO Exception: An EventMachine loop must be running to use publish_async calls` or @@ -341,35 +362,38 @@ If you write a script that uses `publish_async`, you need to keep the script alive long enough for the call(s) to complete. EventMachine itself won't do this because it runs in a different thread. Here's an [example gist](https://gist.github.com/dzello/7472823) that shows how to exit the process after the event has been recorded. ### Changelog +##### 0.8.8 ++ Add support for a configurable read timeout + ##### 0.8.7 + Add support for returning all keys back from query API responses ##### 0.8.6 + Add support for getting [query URLs](https://github.com/keenlabs/keen-gem/pull/47) + Make the `query` method public so code supporting dynamic analysis types is easier to write ##### 0.8.4 -+ Add support for getting [project details](https://keen.io/docs/api/reference/#project-row-resource) ++ Add support for getting [project details](https://keen.io/docs/api/reference/#project-row-resource?s=gh-gem) ##### 0.8.3 -+ Add support for getting a list of a [project's collections](https://keen.io/docs/api/reference/#event-resource) ++ Add support for getting a list of a [project's collections](https://keen.io/docs/api/reference/#event-resource?s=gh-gem) ##### 0.8.2 + Add support for `median` and `percentile` analysis + Support arrays for extraction `property_names` option ##### 0.8.1 + Add support for asynchronous batch publishing ##### 0.8.0 + **UPGRADE WARNING** Do you use spaces in collection names? Or other special characters? Read [this post](https://groups.google.com/forum/?fromgroups#!topic/keen-io-devs/VtCgPuNKrgY) from the mailing list to make sure your collection names don't change. -+ Add support for generating [scoped keys](https://keen.io/docs/security/#scoped-key). ++ Add support for generating [scoped keys](https://keen.io/docs/security/#scoped-key?s=gh-gem). + Make collection name encoding more robust. Make sure collection names are encoded identically for publishing events, running queries, and performing deletes. -+ Add support for [grouping by multiple properties](https://keen.io/docs/data-analysis/group-by/#grouping-by-multiple-properties). ++ Add support for [grouping by multiple properties](https://keen.io/docs/data-analysis/group-by/#grouping-by-multiple-properties?s=gh-gem). ##### 0.7.8 + Add support for redirect URL creation. ##### 0.7.7 @@ -424,12 +448,17 @@ + Added beacon_url support + Add support for using em-synchrony with asynchronous calls ### Questions & Support -If you have any questions, bugs, or suggestions, please -report them via Github Issues. Or, come chat with us anytime -at [users.keen.io](http://users.keen.io). We'd love to hear your feedback and ideas! +For questions, bugs, or suggestions about this gem: +[File a Github Issue](https://github.com/keenlabs/keen-gem/issues). + +For other Keen-IO related technical questions: +['keen-io' on Stack Overflow](http://stackoverflow.com/questions/tagged/keen-io) + +For general Keen IO discussion & feedback: +['keen-io-devs' Google Group](https://groups.google.com/forum/#!forum/keen-io-devs) ### Contributing keen-gem is an open source project and we welcome your contributions. Fire away with issues and pull requests!