Groups and aliases

Author: MrTravisB

README.md

@@ -63,6 +63,27 @@ You can also disable a previously registered device tokens.
 ### User ID
 - A user ID must ALWAYS be a string or a number. Anything else will trigger an error and the call will not be sent to Outbound. User IDs are always stored as strings. Keep this in mind if you have different types. A user with ID of 1 (the number) will be considered the same as user with ID of "1" (the string).
 - A user ID should be static. It should be the same value you use to identify the user in your own system.
+- Some times you don't have a user id yet for a user but you still want to identify them and trigger events for them. You can do this by generating a new ID (call this the anonymous ID) and identify the user as you normally would. Then, once the user becomes a real, identifiable user and you have a real ID for them, make another identify call, this time pass in the anonymous ID as the previous ID.
+
+        user_info = {
+            :previous_id => anonymous_id,
+        }
+        Outbound.identify("USER ID", user_info)
+
+### Groups
+You can create a set of attributes and have them be inherited by a group of users. This can all be done with the `identify` call.
+
+    user_info = {
+        :group_id => 'group identifier',
+        :group_attributes => {
+            ... attributes shared by the group ...
+        }
+    }
+    Outbound.identify("USER ID", user_info)
+
+- Group IDs are treated just like user IDs. They should only be strings or numbers.
+- Users in a group will inherit group attributes but user attributes take precedences. So if there is an attribute `state` set on the group and it is set to "California" and there is also a `state` attribute set on the user but set to "New York", the value for that user is "New York". If the user didn't have that attribute, the value of `state` for that user would be the group value which is "California".
+- You only need to pass in the group attributes when they are initially set or when they are updated but you do need to set the group id for each user you want to be in the group.
 
 ### Event Name
 - An event name in a track can only be a string. Any other type of value will trigger an error and the call will not be sent to Outbound.

lib/outbound.rb

@@ -4,7 +4,7 @@
 require 'uri'
 
 module Outbound
-  VERSION = '0.3.2'
+  VERSION = '0.4.0'
   BASE_URL = 'https://api.outbound.io/v2'
 
   APNS = "apns"
@@ -256,6 +256,9 @@ def user info={}, attributes={}
         :phone_number => info[:phone_number],
         :apns => info[:apns_tokens],
         :gcm => info[:gcm_tokens],
+        :group_id => info[:group_id],
+        :group_attributes => info[:group_attributes],
+        :previous_id => info[:previous_id],
         :attributes => attributes,
       }
       return user.delete_if { |k, v| v.nil? || v.empty? }