README.md in keen-0.8.4 vs README.md in keen-0.8.5
- old
+ new
@@ -1,8 +1,9 @@
# Keen IO Official Ruby Client Library
[](http://travis-ci.org/keenlabs/keen-gem) [](https://codeclimate.com/github/keenlabs/keen-gem)
+[](http://badge.fury.io/rb/keen)
keen-gem is the official Ruby Client for the [Keen IO](https://keen.io/) API. The
Keen IO API lets developers build analytics features directly into their apps.
### Installation
@@ -46,31 +47,30 @@
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.)
Once your environment is properly configured, the `Keen` object is ready to go immediately.
-### Publishing events
+### Synchronous Publishing
Publishing events requires that `KEEN_WRITE_KEY` is set. Publish an event like this:
```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 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 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/).
+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.
### Asynchronous publishing
-Publishing events shouldn't slow your application down or make
-users wait longer for page loads & server requests.
+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.
+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 when latency is a concern. Alternatively, you can drop events into a background queue e.g. Delayed Jobs and publish synchronously from there.
To compare asychronous vs. synchronous performance, check out the [keen-gem-example](http://keen-gem-example.herokuapp.com/) app.
To publish asynchronously, first add
[em-http-request](https://github.com/igrigorik/em-http-request) to your Gemfile. Make sure it's version 1.0 or above.
@@ -89,11 +89,11 @@
```
The best place for this is in an initializer, or anywhere that runs when your app boots up.
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 an example repository that shows an example of [Eventmachine with Unicorn](https://github.com/dzello/em-unicorn/blob/master/unicorn.rb), specifically the Unicorn config for starting and stopping EventMachine after forking.
+And here's a gist that shows an example of [Eventmachine with Unicorn](https://gist.github.com/jonkgrimes/5103321), specifically the Unicorn config for starting and stopping EventMachine after forking.
Now, in your code, replace `publish` with `publish_async`. Bind callbacks if you require them.
```ruby
http = Keen.publish_async("sign_ups", { :username => "lloyd", :referred_by => "harry" })
@@ -141,10 +141,36 @@
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/).
+##### The Query Method
+
+You can also specify the analysis type as a parameter to a method called `query`:
+
+``` ruby
+Keen.query("median", "purchases", :target_property => "price") # => 60
+```
+
+This simplifes querying code where the analysis type is dynamic.
+
+##### Getting Query URLs
+
+Sometimes you just want the URL for a query, but don't actually need to run it. Maybe to paste into a dashboard, or open in your browser. In that case, use the `query_url` method:
+
+``` ruby
+Keen.query_url("median", "purchases", :target_property => "price")
+# => "https://api.keen.io/3.0/projects/<project-id>/queries/median?target_property=price&event_collection=purchases&api_key=<api-key>"
+```
+
+If you don't want the API key included, pass the `:exclude_api_key` option:
+
+``` ruby
+Keen.query_url("median", "purchases", { :target_property => "price" }, :exclude_api_key => true)
+# => "https://api.keen.io/3.0/projects/<project-id>/queries/median?target_property=price&event_collection=purchases"
+```
+
### Listing collections
The Keen IO API let you get the event collections for the project set, it includes properties and their type. It also returns links to the collection resource.
```ruby
@@ -294,9 +320,13 @@
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.5
++ 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)
##### 0.8.3