README.md in pushpad-0.2.1 vs README.md in pushpad-0.3.0

@@ -1,6 +1,6 @@
-# Pushpad: real push notifications for websites
+# Pushpad - Web Push Notifications
 
 Add native push notifications to your web app using [Pushpad](https://pushpad.xyz).
 
 Features:
 
@@ -39,28 +39,30 @@
 ```ruby
 Pushpad.auth_token = '5374d7dfeffa2eb49965624ba7596a09'
 Pushpad.project_id = 123 # set it here or pass it as a param to methods later
 ```
 
-`auth_token` can be found in the user account settings. 
-`project_id` can be found in the project settings on Pushpad. A project is a list of subscriptions. You can set it globally or pass it as a param to methods if your app uses multiple lists (e.g. `Pushpad.path_for current_user, project_id: 123`, `notification.deliver_to user, project_id: 123`).
+- `auth_token` can be found in the user account settings. 
+- `project_id` can be found in the project settings. If your application uses multiple projects, you can pass the `project_id` as a param to methods (e.g. `notification.deliver_to user, project_id: 123`).
 
-## Collecting user subscriptions
+## Collecting user subscriptions to push notifications
 
+Pushpad offers two different ways to collect subscriptions. [Learn more](https://pushpad.xyz/docs#simple_vs_custom_api_docs)
+
 ### Custom API
 
-Read the [docs](https://pushpad.xyz/docs#custom_api_docs).
+Choose the Custom API if you want to use Javascript for a seamless integration. [Read the docs](https://pushpad.xyz/docs#custom_api_docs)
 
 If you need to generate the HMAC signature for the `uid` you can use this helper:
 
 ```ruby
 Pushpad.signature_for current_user.id
 ```
 
 ### Simple API
 
-Let users subscribe to your push notifications: 
+Add a link to let users subscribe to push notifications: 
 
 ```erb
 <a href="<%= Pushpad.path %>">Subscribe anonymous to push notifications</a>
 
 <a href="<%= Pushpad.path_for current_user # or current_user_id %>">Subscribe current user to push notifications</a>
@@ -68,29 +70,39 @@
 
 `current_user` is the user currently logged in on your website.
 
 When a user clicks the link is sent to Pushpad, automatically asked to receive push notifications and redirected back to your website.
 
-## Sending notifications
+## Sending push notifications
 
-After you have collected the user subscriptions you can send them push notifications:
-
 ```ruby
 notification = Pushpad::Notification.new({
-  body: "Hello world!",
-  title: "Website Name", # optional, defaults to your project name
+  body: "Hello world!", # max 90 characters
+  title: "Website Name", # optional, defaults to your project name, max 30 characters
   target_url: "http://example.com" # optional, defaults to your project website
 })
 
+# deliver to a user
 notification.deliver_to user # or user_id
+
+# deliver to a group of users
 notification.deliver_to users # or user_ids
-notification.broadcast # deliver to everyone
+
+# deliver to some users only if they have a given preference
+# e.g. only "users" who have a interested in "events" will be reached
+notification.deliver_to users, tags: ['events']
+
+# deliver to segments
+notification.broadcast tags: ['segment1', 'segment2']
+
+# deliver to everyone
+notification.broadcast
 # => {"scheduled": 12}
 ```
 
 If no user with that id has subscribed to push notifications, that id is simply ignored.
 
-The methods above return an hash: `res["scheduled"]` contains the number of notifications that will be sent. For example if you call `notification.deliver_to user` but the user has never subscribed to push notifications the result will be `{"scheduled": 0}`.
+The methods above return an hash: `"scheduled"` is the number of devices to which the notification will be sent.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).