README.md in keen-0.7.3 vs README.md in keen-0.7.4

- old
+ new

@@ -21,42 +21,52 @@ * Rubinius * 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 both of your Write and Read Keys. -(If you need a Keen IO account, [sign up here](https://keen.io/) - it's free.) The Write key is required for publishing -events, and the Read key is required for running queries. +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.) -The recommended way to do this is to set `KEEN_PROJECT_ID`, `KEEN_WRITE_KEY`, and `KEEN_READ_KEY` in your -environment. If you're using [foreman](http://ddollar.github.com/foreman/), add this to your `.env` file: +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). - KEEN_PROJECT_ID=xxxxxxxxxxxxxxxx KEEN_WRITE_KEY=yyyyyyyyyyyyy KEEN_READ_KEY=zzzzzzzzzzzzz +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`. +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 + KEEN_WRITE_KEY=yyyyyyyyyyyyyyy + KEEN_READ_KEY=zzzzzzzzzzzzzzz + If not, make to to export the variable into your shell or put it before the command you use to start your server. When you deploy, make sure your production environment variables are set. For example, set [config vars](https://devcenter.heroku.com/articles/config-vars) on Heroku. (We recommend this environment-based approach because it keeps sensitive information out of the codebase. If you can't do this, see the alternatives below.) -If your environment is set up property, `Keen` is ready to go immediately. Publish an event like this: +Once your environment is properly configured, the `Keen` object is ready to go immediately. +### Publishing events + +Publishing events requires that `KEEN_WRITE_KEY` is set. Publish an event like this: + ```ruby -Keen.publish("sign_ups", { :username => "lloyd", :referred_by => "harry" }) +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. +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 and nested properties are allowed. 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 are arbitrary JSON, and the event collection need not exist in advance. -If it doesn't exist, Keen IO will create it on the first request. +The event collection need not exist in advance. If it doesn't exist, Keen IO will create it on the first request. -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/). - ### Asynchronous publishing -Publishing events shouldn't slow your application down. It shouldn't make your -users wait longer for their request to finish. +Publishing events shouldn't slow your application down or make +users wait longer for page loads & server requests. The Keen IO API is fast, but any synchronous network call you make will negatively impact response times. For this reason, we recommend you use the `publish_async` method to send events. @@ -75,11 +85,11 @@ ```ruby Thread.new { EventMachine.run } ``` The best place for this is in an initializer, or anywhere that runs when your app boots up. -Here's a good blog article that explains more about this approach - [EventMachine and Passenger](http://railstips.org/blog/archives/2011/05/04/eventmachine-and-passenger/). +Here's a useful blog article that explains more about this approach - [EventMachine and Passenger](http://railstips.org/blog/archives/2011/05/04/eventmachine-and-passenger/). And here's a gist that shows an example of [Eventmachine with Unicorn](https://gist.github.com/jonkgrimes/5103321). Thanks to [jonkgrimes](https://github.com/jonkgrimes) for sharing this with us! Now, in your code, replace `publish` with `publish_async`. Bind callbacks if you require them. @@ -94,27 +104,25 @@ ### 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/). -Queries require that a Read Key is provided. Just like project ID, we encourage that you set this as an environment variable: +Running queries requires that `KEEN_READ_KEY` is set. - KEEN_READ_KEY=yyyyyyyyyyyyyyyy +Here are some examples of querying with keen-gem. Let's assume you've added some events to the "purchases" collection. -Here's are some examples of querying with keen-gem. Let's assume you've added some events to the "purchases" collection. - ```ruby Keen.count("purchases") # => 100 Keen.sum("purchases", :target_property => "price") # => 10000 Keen.minimum("purchases", :target_property => "price") # => 20 Keen.maximum("purchases", :target_property => "price") # => 100 Keen.average("purchases", :target_property => "price") # => 60 Keen.sum("purchases", :target_property => "price", :group_by => "item.id") # => [{ "item.id": 123, "result": 240 }, { ... }] Keen.count_unique("purchases", :target_property => "username") # => 3 -Keen.select_unique("purchases", :target_property => "username") # => ["bob", "linda", "travis"] +Keen.select_unique("purchases", :target_property => "username") # => ["Bob", "Linda", "Travis"] Keen.extraction("purchases") # => [{ "price" => 20, ... }, { ... }] Keen.funnel(:steps => [ { :actor_property => "username", :event_collection => "purchases" }, @@ -125,14 +133,33 @@ :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}, { ... }] ``` -Many of there queries can be performed with group by, filters, series and intervals. The API response for these is converted directly into Ruby Hash or Array. +Many of there 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/). +### Deleting events + +The Keen IO API allows you to [delete events](https://keen.io/docs/maintenance/#deleting-event-collections) +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 +# Assume some events in the 'signups' collection + +# We can delete them all +Keen.delete(:signups) # => true + +# Or just delete an event corresponding to a particular user +Keen.delete(:signups, filters: [{ + property_name: 'username', operator: 'eq', property_value: "Bob" +}]) # => true +``` + ### Other code examples #### Batch publishing The keen-gem supports publishing events in batches via the `publish_batch` method. Here's an example usage: @@ -151,26 +178,28 @@ ``` This call would publish 2 `signups` events and 2 `purchases` events - all in just one API call. Batch publishing is ideal for loading historical events into Keen IO. -#### Authentication +#### Configurable and per-client authentication To configure keen-gem in code, do as follows: ```ruby Keen.project_id = 'xxxxxxxxxxxxxxx' Keen.write_key = 'yyyyyyyyyyyyyyy' Keen.read_key = 'zzzzzzzzzzzzzzz' +Keen.master_key = 'aaaaaaaaaaaaaaa' ``` -You can also configure individual client instances as follows: +You can also configure unique client instances as follows: ```ruby keen = Keen::Client.new(:project_id => 'xxxxxxxxxxxxxxx', :write_key => 'yyyyyyyyyyyyyyy', - :read_key => 'zzzzzzzzzzzzzzz') + :read_key => 'zzzzzzzzzzzzzzz', + :master_key => 'aaaaaaaaaaaaaaa') ``` #### em-synchrony keen-gem can be used with [em-synchrony](https://github.com/igrigorik/em-synchrony). @@ -194,9 +223,13 @@ ``` To track email opens, simply add an image to your email template that points to this URL. ### Changelog + +##### 0.7.4 ++ Add support for deletes (thanks again [cbartlett](https://github.com/cbartlett)!) ++ Allow event collection names for publishing/deleting methods to be symbols ##### 0.7.3 + Add batch publishing support + Allow event collection names for querying methods to be symbols. Thanks to [cbartlett](https://github.com/cbartlett).