Associate named user by email

docs/named_user.rst

@@ -40,6 +40,23 @@ Associate a channel with a named user ID. For more information, see
 
     Do not include a ``device_type`` for Web and Open platform associations.
 
+Association by email
+-----------
+
+Associate an email with a named user ID. For more information, see
+`the API documentation
+<http://docs.airship.com/api/ua.html#association>`__
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'app_or_master_secret')
+    named_user = UA::NamedUser.new(client: airship)
+    named_user.named_user_id = 'named_user'
+    named_user.associate_by_email_address(email_address: 'email_address')
+
+
 Disassociation
 --------------
 

lib/urbanairship/devices/named_user.rb

@@ -42,6 +42,24 @@ def associate(channel_id: required('channel_id'), device_type: nil)
         response
       end
 
+      def associate_by_email_address(email_address: required('email_address'))
+        fail ArgumentError,
+             'named_user_id is required for association' if @named_user_id.nil?
+
+        payload = {}
+        payload['email_address'] = email_address
+        payload['named_user_id'] = @named_user_id.to_s
+
+        response = @client.send_request(
+          method: 'POST',
+          body: JSON.dump(payload),
+          path: named_users_path('associate'),
+          content_type: CONTENT_TYPE
+        )
+        logger.info { "Associated email_address #{email_address} with named_user #{@named_user_id}" }
+        response
+      end
+
       def disassociate(channel_id: required('channel_id'), device_type: nil)
         payload = {}
         payload['channel_id'] = channel_id

spec/lib/urbanairship/devices/named_user_spec.rb

@@ -7,6 +7,7 @@
   let(:channel_id) { '123' }
   let(:device_type) { 'android' }
   let(:named_user_id) { 'user' }
+  let(:email_address) { '[email protected]' }
 
   named_user = nil
 
@@ -112,6 +113,48 @@
       end
     end
 
+    describe '#associate_by_email_address' do
+      describe 'Request' do
+        after(:each) { named_user.associate_by_email_address(email_address: email_address) }
+
+        it 'makes the expected request' do
+          allow(airship).to receive(:send_request) do |arguments|
+            expect(arguments).to eq(
+              method: 'POST',
+              body: { email_address: email_address, named_user_id: named_user_id }.to_json,
+              path: "/named_users/associate",
+              content_type: described_class::CONTENT_TYPE,
+            )
+            expected_response
+          end
+        end
+
+        context 'Named user ID is an integer' do
+          let(:named_user_id) { 1985 }
+
+          it 'converts named user ID to a string' do
+            allow(airship).to receive(:send_request) do |arguments|
+              expect(JSON.parse(arguments[:body], symbolize_names: true)[:named_user_id]).to eq named_user_id.to_s
+              expected_response
+            end
+          end
+        end
+      end
+
+      it 'associates a email_address with a named_user' do
+        allow(airship).to receive(:send_request).and_return(expected_response)
+        actual_resp = named_user.associate_by_email_address(email_address: email_address)
+        expect(actual_resp).to eq(expected_response)
+      end
+
+      it 'fails when the user_id is not set' do
+        named_user_without_id = UA::NamedUser.new(client: airship)
+        expect {
+          named_user_without_id.associate_by_email_address(email_address: email_address)
+        }.to raise_error(ArgumentError)
+      end
+    end
+
     describe '#disassociate' do
       it 'disassociates a channel from a named_user' do
         allow(airship).to receive(:send_request).and_return(expected_response)