urbanairship 2.2.0 → 2.2.1

data/README.markdown

@@ -24,6 +24,13 @@ Registering a device token
 ```ruby
 Urbanairship.register_device('DEVICE-TOKEN')
 ```
+You can also pass an alias, and a set of tags to device registration.
+```ruby
+Urbanairship.register_device('DEVICE-TOKEN',
+  :alias => 'user-123',
+  :tags => ['san-francisco-users']
+)
+```
 
 Unregistering a device token
 ----------------------------
@@ -65,6 +72,26 @@ notifications = [
 Urbanairship.batch_push(notifications)
 ```
 
+Sending notifications to a segment
+---------------------------
+Urban Airship segments let you send a push notification to a subset of relevant users based on location, time, preferences, and behavior. You can read more about segments in the [Urban Airship docs](https://docs.urbanairship.com/display/DOCS/Server%3A+Segments+API).
+
+```ruby
+notification = {
+  :schedule_for => [1.hour.from_now],
+  :segments => ['SEGMENT-ID'],
+  :ios => {
+    :aps => {
+      :alert => 'You have a new message!', :badge => 1
+    }
+  },
+  :android => {
+    :alert => 'You have a new message!', :badge => 1
+  }
+}
+
+Urbanairship.push_to_segment(notification)
+```
 
 Sending broadcast notifications
 -------------------------------
@@ -111,6 +138,68 @@ Urbanairship.delete_scheduled_push(123456789)
 Urbanairship.delete_scheduled_push(:alias => "deadbeef")
 ```
 
+Tags
+----
+
+Urban Airship allows you to create tags and associate them with devices. Then you can easily send a notification to every device matching a certain tag with a single call to the push API.
+
+### Creating a tag ###
+
+Tags must be registered before you can use them.
+
+```ruby
+Urbanairship.add_tag('TAG')
+```
+
+### Listing your tags ###
+
+```ruby
+Urbanairship.tags
+```
+
+### Removing a tag ##
+
+This will remove a tag from your set of registered tags, as well as removing that tag from any devices that are currently using it.
+
+```ruby
+Urbanairship.remove_tag('TAG')
+```
+
+### View tags associated with device ###
+
+```ruby
+Urbanairship.tags_for_device('DEVICE-TOKEN')
+```
+
+### Tag a device ###
+
+```ruby
+Urbanairship.tag_device(:device_token => 'DEVICE-TOKEN', :tag => 'TAG')
+```
+
+You can also tag a device during device registration.
+
+```ruby
+Urbanairship.register_device('DEVICE-TOKEN', :tags => ['san-francisco-users'])
+```
+
+### Untag a device ###
+
+```ruby
+Urbanairship.untag_device(:device_token => 'DEVICE-TOKEN', :tag => 'TAG')
+```
+
+### Sending a notification to all devices with a given tag ###
+
+```ruby
+notification = {
+  :tags => ['san-francisco-users'],
+  :aps => {:alert => 'Good morning San Francisco!', :badge => 1}
+}
+
+Urbanairship.push(notification)
+```
+
 Using Urbanairship with Android
 -------------------------------
 

data/lib/urbanairship.rb

@@ -44,6 +44,11 @@ module Urbanairship
       do_request(:post, "/api/push/", :body => body, :authenticate_with => :master_secret)
     end
 
+    def push_to_segment(options = {})
+      body = parse_push_options(options).to_json
+      do_request(:post, "/api/push/segments", :body => body, :authenticate_with => :master_secret)
+    end
+
     def batch_push(notifications = [])
       body = notifications.map{|notification| parse_push_options(notification)}.to_json
       do_request(:post, "/api/push/batch/", :body => body, :authenticate_with => :master_secret)
@@ -58,6 +63,30 @@ module Urbanairship
       do_request(:get, "/api/device_tokens/feedback/?since=#{format_time(time)}", :authenticate_with => :master_secret)
     end
 
+    def tags
+      do_request(:get, "/api/tags/", :authenticate_with => :master_secret)
+    end
+
+    def add_tag(tag)
+      do_request(:put, "/api/tags/#{tag}", :authenticate_with => :master_secret)
+    end
+
+    def remove_tag(tag)
+      do_request(:delete, "/api/tags/#{tag}", :authenticate_with => :master_secret)
+    end
+
+    def tags_for_device(device_token)
+      do_request(:get, "/api/device_tokens/#{device_token}/tags", :authenticate_with => :master_secret)
+    end
+
+    def tag_device(params)
+      do_request(:put, "/api/device_tokens/#{params[:device_token]}/tags/#{params[:tag]}", :authenticate_with => :master_secret)
+    end
+
+    def untag_device(params)
+      do_request(:delete, "/api/device_tokens/#{params[:device_token]}/tags/#{params[:tag]}", :authenticate_with => :master_secret)
+    end
+
     private
 
     def do_request(http_method, path, options = {})

data/spec/urbanairship_spec.rb

@@ -35,6 +35,41 @@ shared_examples_for "an Urbanairship client" do
     # feedback
     FakeWeb.register_uri(:get, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/device_tokens\/feedback/, :status => ["200", "OK"], :body => "[{\"device_token\":\"token\",\"marked_inactive_on\":\"2010-10-14T19:15:13Z\",\"alias\":\"my_alias\"}]")
     FakeWeb.register_uri(:get, /my_app_key2\:my_master_secret2\@go\.urbanairship.com\/api\/device_tokens\/feedback/, :status => ["500", "Internal Server Error"])
+    
+    #tags
+    FakeWeb.register_uri(:get, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/tags/, :status => ["200", "OK"], :body => "[{\"tags\":[\"tag1\",\"tag2\"]}]")
+    FakeWeb.register_uri(:get, /my_app_key2\:my_master_secret2\@go\.urbanairship.com\/api\/tags/, :status => ["500", "Internal Server Error"])
+    
+    #add_tag
+    FakeWeb.register_uri(:put, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/tags\/new_tag/, :status => ["200", "OK"])
+    FakeWeb.register_uri(:put, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/tags\/existing_tag/, :status => ["201", "OK"])
+    FakeWeb.register_uri(:put, /my_app_key2\:my_master_secret2\@go\.urbanairship.com\/api\/tags\/a_tag/, :status => ["500", "Internal Server Error"])
+    
+    #remove_tag
+    FakeWeb.register_uri(:delete, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/tags\/non_deleted_tag/, :status => ["204", "OK"])
+    FakeWeb.register_uri(:delete, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/tags\/deleted_tag/, :status => ["404", "OK"])
+    FakeWeb.register_uri(:delete, /my_app_key2\:my_master_secret2\@go\.urbanairship.com\/api\/tags\/a_tag/, :status => ["500", "Internal Server Error"])
+    
+    #tags_for_device_tokens
+    FakeWeb.register_uri(:get, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/device_tokens\/valid_device_token\/tags/, :status => ["200", "OK"], :body => "[{\"tags\":[\"tag1\",\"tag2\"]}]")
+    FakeWeb.register_uri(:get, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/device_tokens\/invalid_device_token\/tags/, :status => ["404", "OK"])
+    FakeWeb.register_uri(:get, /my_app_key2\:my_master_secret2\@go\.urbanairship.com\/api\/device_tokens\/a_device_token\/tags/, :status => ["500", "Internal Server Error"])
+    
+    ##tag_device
+    FakeWeb.register_uri(:put, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/device_tokens\/valid_device_token\/tags\/new_tag/, :status => ["201", "OK"])
+    FakeWeb.register_uri(:put, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/device_tokens\/valid_device_token\/tags\/existing_tag/, :status => ["200", "OK"])
+    FakeWeb.register_uri(:put, /my_app_key2\:my_master_secret2\@go\.urbanairship.com\/api\/device_tokens\/a_device_token\/tags\/a_tag/, :status => ["500", "Internal Server Error"])
+    
+    #untag_device
+    FakeWeb.register_uri(:delete, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/device_tokens\/valid_device_token\/tags\/existing_tag/, :status => ["204", "OK"])
+    FakeWeb.register_uri(:delete, /my_app_key\:my_master_secret\@go\.urbanairship.com\/api\/device_tokens\/valid_device_token\/tags\/non_existant_tag/, :status => ["404", "OK"])
+    FakeWeb.register_uri(:delete, /my_app_key2\:my_master_secret2\@go\.urbanairship.com\/api\/device_tokens\/a_device_token\/tags\/a_tag/, :status => ["500", "Internal Server Error"])
+    
+    # push to segment
+    FakeWeb.register_uri(:post, "https://my_app_key:my_master_secret@go.urbanairship.com/api/push/segments", :status => ["200", "OK"])
+    FakeWeb.register_uri(:post, "https://my_app_key2:my_master_secret2@go.urbanairship.com/api/push/segments", :status => ["400", "Bad Request"])
+    FakeWeb.register_uri(:post, /bad_key\:my_master_secret\@go\.urbanairship\.com/, :status => ["401", "Unauthorized"])
+    
   end
 
   describe "configuration" do
@@ -56,6 +91,223 @@ shared_examples_for "an Urbanairship client" do
       subject.master_secret.should == "asdf1234"
     end
   end
+  
+  describe "::tags" do
+    before(:each) do
+      subject.application_key = "my_app_key"
+      subject.master_secret = "my_master_secret"
+    end
+
+    it "raises an error if call is made without an app key and master secret configured" do
+      subject.application_key = nil
+      subject.master_secret = nil
+
+      lambda {
+        subject.tags
+      }.should raise_error(RuntimeError, "Must configure application_key, master_secret before making this request.")
+    end
+    
+    it "uses app key and secret to sign the request" do
+      subject.tags
+      FakeWeb.last_request['authorization'].should == "Basic #{Base64::encode64('my_app_key:my_master_secret').chomp}"
+    end
+    
+    it "returns valid tags" do
+      response = subject.tags
+      response.first.should include("tags")
+      response.first["tags"].should include("tag1")
+      response.first["tags"].should include("tag2")
+    end
+    
+    it "success? is false when the call doesn't return 200" do
+      subject.application_key = "my_app_key2"
+      subject.master_secret = "my_master_secret2"
+      subject.tags.success?.should == false
+    end
+   
+  end
+  
+  describe "::add_tag" do
+    before(:each) do
+      subject.application_key = "my_app_key"
+      subject.master_secret = "my_master_secret"
+    end
+
+    it "raises an error if call is made without an app key and master secret configured" do
+      subject.application_key = nil
+      subject.master_secret = nil
+
+      lambda {
+        subject.add_tag('a_tag')
+      }.should raise_error(RuntimeError, "Must configure application_key, master_secret before making this request.")
+    end
+    
+    it "uses app key and secret to sign the request" do
+      subject.add_tag('new_tag')
+      FakeWeb.last_request['authorization'].should == "Basic #{Base64::encode64('my_app_key:my_master_secret').chomp}"
+    end
+    
+    it "adds a new tag" do
+      subject.add_tag('new_tag').success?.should == true
+      subject.add_tag('new_tag').code.should == "200"
+    end
+    
+    it "adds an exisiting tag" do
+      subject.add_tag('existing_tag').success?.should == true
+      subject.add_tag('existing_tag').code.should == "201"
+    end
+    
+    it "success? is false when the call doesn't return 200 or 201" do
+      subject.application_key = "my_app_key2"
+      subject.master_secret = "my_master_secret2"
+      subject.add_tag('a_tag').success?.should == false
+    end
+   
+  end
+  
+  describe "::remove_tag" do
+    before(:each) do
+      subject.application_key = "my_app_key"
+      subject.master_secret = "my_master_secret"
+    end
+
+   it "raises an error if call is made without an app key and master secret configured" do
+     subject.application_key = nil
+     subject.master_secret = nil
+
+     lambda {
+       subject.remove_tag('a_tag')
+     }.should raise_error(RuntimeError, "Must configure application_key, master_secret before making this request.")
+   end
+
+   it "uses app key and secret to sign the request" do
+     subject.remove_tag('non_deleted_tag')
+     FakeWeb.last_request['authorization'].should == "Basic #{Base64::encode64('my_app_key:my_master_secret').chomp}"
+   end
+
+   it "removes a tag that has not been removed yet" do
+     subject.remove_tag('non_deleted_tag').success?.should == true
+     subject.remove_tag('non_deleted_tag').code.should == "204"
+   end
+
+   it "attempts to remove an already deleted tag" do
+     subject.remove_tag('deleted_tag').success?.should == false
+     subject.remove_tag('deleted_tag').code.should == "404"
+   end
+   
+   it "success? is false when the call doesn't return 204" do
+     subject.application_key = "my_app_key2"
+     subject.master_secret = "my_master_secret2"
+     subject.add_tag('a_tag').success?.should == false
+   end
+  end
+   
+  describe "::tags_for_device" do
+    before(:each) do
+      subject.application_key = "my_app_key"
+      subject.master_secret = "my_master_secret"
+    end
+    
+    it "raises an error if call is made without an app key and master secret configured" do
+       subject.application_key = nil
+       subject.master_secret = nil
+
+       lambda {
+         subject.tags_for_device('a_device_token')
+       }.should raise_error(RuntimeError, "Must configure application_key, master_secret before making this request.")
+    end
+    
+    it "uses app key and secret to sign the request" do
+      subject.tags_for_device('valid_device_token')
+      FakeWeb.last_request['authorization'].should == "Basic #{Base64::encode64('my_app_key:my_master_secret').chomp}"
+    end
+    
+    it "returns valid tags for a device" do
+      response = subject.tags_for_device('valid_device_token')
+      response.first.should include("tags")
+      response.first["tags"].should include("tag1")
+      response.first["tags"].should include("tag2")
+      response.code.should == "200"
+    end
+    
+    it "returns invalid response for device token that is not found or registered" do
+      response = subject.tags_for_device('invalid_device_token')
+      response.code.should == "404"
+    end
+    
+    it "success? is false when the call doesn't return 200" do
+      subject.application_key = "my_app_key2"
+      subject.master_secret = "my_master_secret2"
+      subject.tags_for_device('a_device_token').success?.should == false
+    end
+  end
+  
+  describe "::tag_device" do
+    before(:each) do
+      subject.application_key = "my_app_key"
+      subject.master_secret = "my_master_secret"
+    end
+    
+    it "raises an error if call is made without an app key and master secret configured" do
+       subject.application_key = nil
+       subject.master_secret = nil
+
+       lambda {
+         subject.tag_device({:device_token => 'a_device_token', :tag => 'a_tag'})
+       }.should raise_error(RuntimeError, "Must configure application_key, master_secret before making this request.")
+    end
+    
+    it "uses app key and secret to sign the request" do
+      subject.tag_device({:device_token => 'valid_device_token', :tag => 'new_tag'})
+      FakeWeb.last_request['authorization'].should == "Basic #{Base64::encode64('my_app_key:my_master_secret').chomp}"
+    end
+    
+    it "adds a valid device token to tag" do
+      response = subject.tag_device({:device_token => 'valid_device_token', :tag => 'new_tag'})
+      response.code.should == "201"
+      response.success?.should == true
+    end
+    
+    it "adds a valid device token to an existing tag" do
+      response = subject.tag_device({:device_token => 'valid_device_token', :tag => 'existing_tag'})
+      response.code.should == "200"
+      response.success?.should == true
+    end
+  end
+    
+    describe "::untag_device" do
+      before(:each) do
+        subject.application_key = "my_app_key"
+        subject.master_secret = "my_master_secret"
+      end
+
+      it "raises an error if call is made without an app key and master secret configured" do
+         subject.application_key = nil
+         subject.master_secret = nil
+
+         lambda {
+           subject.untag_device({:device_token => 'a_device_token', :tag => 'a_tag'})
+         }.should raise_error(RuntimeError, "Must configure application_key, master_secret before making this request.")
+      end
+
+      it "uses app key and secret to sign the request" do
+        subject.untag_device({:device_token => 'valid_device_token', :tag => 'existing_tag'})
+        FakeWeb.last_request['authorization'].should == "Basic #{Base64::encode64('my_app_key:my_master_secret').chomp}"
+      end
+
+      it "removes a valid device token from a tag" do
+        response = subject.untag_device({:device_token => 'valid_device_token', :tag => 'existing_tag'})
+        response.code.should == "204"
+        response.success?.should == true
+      end
+
+      it "removes a device token from a tag that it is not associated with" do
+        response = subject.untag_device({:device_token => 'valid_device_token', :tag => 'non_existant_tag'})
+        response.code.should == "404"
+        response.success?.should == false
+      end
+  end
+  
 
   describe "::register_device" do
     before(:each) do
@@ -270,6 +522,54 @@ shared_examples_for "an Urbanairship client" do
       subject.push.success?.should == false
     end
   end
+  
+  describe "::push_to_segment" do
+    before(:each) do
+      @valid_params = {:segments => ['segment-id'], :aps => {:alert => 'foo'}}
+      subject.application_key = "my_app_key"
+      subject.master_secret = "my_master_secret"
+    end
+
+    it "raises an error if call is made without an app key and master secret configured" do
+      subject.application_key = nil
+      subject.master_secret = nil
+
+      lambda {
+        subject.push(@valid_params)
+      }.should raise_error(RuntimeError, "Must configure application_key, master_secret before making this request.")
+    end
+
+    it "uses app key and secret to sign the request" do
+      subject.push_to_segment(@valid_params)
+      FakeWeb.last_request['authorization'].should == "Basic #{Base64::encode64('my_app_key:my_master_secret').chomp}"
+    end
+
+    it "returns true when it successfully pushes a notification" do
+      subject.push_to_segment(@valid_params).success?.should == true
+    end
+
+    it "returns false when the authorization is invalid" do
+      subject.application_key = "bad_key"
+      subject.push_to_segment(@valid_params).success?.should == false
+    end
+
+    it "adds schedule_for to the JSON payload" do
+      time = Time.parse("Oct 17th, 2010, 8:00 PM UTC")
+      subject.push_to_segment(@valid_params.merge(:schedule_for => [time]))
+      request_json['schedule_for'].should == ['2010-10-17T20:00:00Z']
+    end
+
+    it "only attempts to format schedule_for if it is a time object" do
+      subject.push_to_segment(@valid_params.merge(:schedule_for => ["2010-10-10 09:09:09 UTC"]))
+      request_json['schedule_for'].should == ['2010-10-10T09:09:09Z']
+    end
+
+    it "returns false if urbanairship responds with a non-200 response" do
+      subject.application_key = "my_app_key2"
+      subject.master_secret = "my_master_secret2"
+      subject.push_to_segment.success?.should == false
+    end
+  end
 
   describe "::batch_push" do
     before(:each) do

metadata

@@ -1,75 +1,72 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: urbanairship
-version: !ruby/object:Gem::Version 
-  hash: 7
+version: !ruby/object:Gem::Version
+  version: 2.2.1
   prerelease: 
-  segments: 
-  - 2
-  - 2
-  - 0
-  version: 2.2.0
 platform: ruby
-authors: 
+authors:
 - Groupon, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-11-08 00:00:00 -06:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2013-01-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: json
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: fakeweb
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fakeweb
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id003
-description: Urbanairship is a Ruby library for interacting with the Urban Airship (http://urbanairship.com) API.
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Urbanairship is a Ruby library for interacting with the Urban Airship
+  (http://urbanairship.com) API.
+email:
 - rubygems@groupon.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - README.markdown
 - LICENSE
 - Rakefile
@@ -78,43 +75,31 @@ files:
 - spec/response_spec.rb
 - spec/spec_helper.rb
 - spec/urbanairship_spec.rb
-has_rdoc: true
 homepage: http://github.com/groupon/urbanairship
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 59
-      segments: 
-      - 1
-      - 8
-      - 6
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
       version: 1.8.6
-required_rubygems_version: !ruby/object:Gem::Requirement 
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A Ruby wrapper for the Urban Airship API
-test_files: 
+test_files:
 - spec/response_spec.rb
 - spec/spec_helper.rb
 - spec/urbanairship_spec.rb