README.md in keen-0.7.8 vs README.md in keen-0.8.0

- old
+ new

@@ -38,11 +38,11 @@ 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. +If not, make a script to export the variables 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.) @@ -87,11 +87,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 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! +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. 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" }) @@ -152,11 +152,11 @@ # 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" + :property_name => 'username', ;operator => 'eq', :property_value => "Bob" }]) # => true ``` ### Other code examples @@ -205,11 +205,11 @@ keen-gem can be used with [em-synchrony](https://github.com/igrigorik/em-synchrony). If you call `publish_async` and `EM::Synchrony` is defined the method will return the response directly. (It does not return the deferrable on which to register callbacks.) Likewise, it will raise exceptions 'synchronously' should they happen. -#### Beacon URL's +#### Beacon URLs It's possible to publish events to your Keen IO project using the HTTP GET method. This is useful for situations like tracking email opens using [image beacons](http://en.wikipedia.org/wiki/Web_bug). In this situation, the JSON event data is passed by encoding it base-64 and adding it as a request parameter called `data`. @@ -220,25 +220,63 @@ 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. +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/). -#### Redirect URL's -Redirect URL's are just like image beacon URL's with the addition of a `redirect` query parameter. This parameter is used +#### 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. ``` 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. +This is helpful for tracking email clickthroughs. See the [redirect documentation](https://keen.io/docs/data-collection/redirect/) 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. +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" => [{ + "property_name" => "accountId", + "operator" => "eq", + "property_value" => "123456" +}]}).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. + +### Troubleshooting + +##### EventMachine + +If you run into `Keen::Error: Keen IO Exception: An EventMachine loop must be running to use publish_async calls` or +`Uncaught RuntimeError: eventmachine not initialized: evma_set_pending_connect_timeout`, this means that the EventMachine +loop has died. This can happen for a variety of reasons, and every app is different. [Issue #22](https://github.com/keenlabs/keen-gem/issues/22) shows how to add some extra protection to avoid this situation. + +##### publish_async in a script or worker + +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.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). ++ 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). + +##### 0.7.8 ++ Add support for redirect URL creation. + ##### 0.7.7 + Add support for HTTP and SOCKS proxies. Set `KEEN_PROXY_URL` to the proxy URL and `KEEN_PROXY_TYPE` to 'socks5' if you need to. These properties can also be set on the client instances as `proxy_url` and `proxy_type`. + Delegate the `master_key` fields from the Keen object. @@ -296,9 +334,25 @@ at [users.keen.io](http://users.keen.io). We'd love to hear your feedback and ideas! ### Contributing keen-gem is an open source project and we welcome your contributions. Fire away with issues and pull requests! + +#### Running Tests + +`bundle exec rake spec` - Run unit specs. HTTP is mocked. + +`bundle exec rake integration` - Run integration specs with the real API. Requires env variables. See [.travis.yml](https://github.com/keenlabs/keen-gem/blob/master/.travis.yml). + +`bundle exec rake synchrony` - Run async publishing specs with `EM::Synchrony`. + +Similarly, you can use guard to listen for changes to files and run specs. + +`bundle exec guard -g unit` + +`bundle exec guard -g integration` + +`bundle exec guard -g synchrony` ### Community Contributors + [alexkwolfe](https://github.com/alexkwolfe) + [peteygao](https://github.com/peteygao) + [obieq](https://github.com/obieq)