Merge pull request #101 from pusher/native-notifications

Native notifications

Author: vivangkumar

README.md

@@ -247,3 +247,63 @@ else
   render text: 'invalid', status: 401
 end
 ```
+
+## Push Notifications (BETA)
+
+Pusher now allows sending native notifications to iOS and Android devices. Check out the [documentation](https://pusher.com/docs/push_notifications) for information on how to set up push notifications on Android and iOS. There is no additional setup required to use it with this library. It works out of the box wit the same Pusher instance. All you need are the same pusher credentials.
+
+### Sending native pushes
+
+The native notifications API is hosted at `nativepush-cluster1.pusher.com` and only accepts https requests.
+
+You can send pushes by using the `notify` method, either globally or on the instance. The method takes two parameters:
+
+- `interests`: An Array of strings which represents the interests your devices are subscribed to. These are akin to channels in the DDN with less of an epehemeral nature. Note that currently, you can only send to _one_ interest.
+- `data`: The content of the notification represented by a Hash. You must supply either the `gcm` or `apns` key. For a detailed list of the acceptable keys, take a look at the [iOS](https://pusher.com/docs/push_notifications/ios/server) and [Android](https://pusher.com/docs/push_notifications/android/server) docs.
+
+Example:
+
+```ruby
+data = {
+  apns: {
+    aps: {
+      alert: {
+        body: 'tada'
+      }
+    }
+  }
+}
+
+pusher.notify(["my-favourite-interest"], data)
+```
+
+### Errors
+
+Push notification requests, once submitted to the service are executed asynchronously. To make reporting errors easier, you can supply a `webhook_url` field in the body of the request. This will be used by the service to send a webhook to the supplied URL if there are errors.
+
+You may also supply a `webhook_level` field in the body, which can either be INFO or DEBUG. It defaults to INFO - where INFO only reports customer facing errors, while DEBUG reports all errors.
+
+For example:
+
+```ruby
+data = {
+  apns: {
+    aps: {
+      alert: {
+        body: "hello"
+      }
+    }
+  },
+  gcm: {
+    notification: {
+      title: "hello",
+      icon: "icon"
+    }
+  },
+  webhook_url: "http://yolo.com",
+  webhook_level: "INFO"
+}
+```
+
+**NOTE:** This is currently a BETA feature and there might be minor bugs and issues. Changes to the API will be kept to a minimum, but changes are expected. If you come across any bugs or issues, please do get in touch via [support](support@pusher.com) or create an issue here.
+

lib/pusher.rb

@@ -28,7 +28,9 @@ class << self
     extend Forwardable
 
     def_delegators :default_client, :scheme, :host, :port, :app_id, :key, :secret, :http_proxy
+    def_delegators :default_client, :notification_host, :notification_scheme
     def_delegators :default_client, :scheme=, :host=, :port=, :app_id=, :key=, :secret=, :http_proxy=
+    def_delegators :default_client, :notification_host=, :notification_scheme=
 
     def_delegators :default_client, :authentication_token, :url
     def_delegators :default_client, :encrypted=, :url=, :cluster=
@@ -37,6 +39,7 @@ class << self
     def_delegators :default_client, :get, :get_async, :post, :post_async
     def_delegators :default_client, :channels, :channel_info, :channel_users, :trigger, :trigger_async
     def_delegators :default_client, :authenticate, :webhook, :channel, :[]
+    def_delegators :default_client, :notify
 
     attr_writer :logger
 
@@ -61,3 +64,4 @@ def default_client
 require 'pusher/request'
 require 'pusher/resource'
 require 'pusher/webhook'
+require 'pusher/native_notification/client'

lib/pusher/client.rb

@@ -2,7 +2,7 @@
 
 module Pusher
   class Client
-    attr_accessor :scheme, :host, :port, :app_id, :key, :secret
+    attr_accessor :scheme, :host, :port, :app_id, :key, :secret, :notification_host, :notification_scheme
     attr_reader :http_proxy, :proxy
     attr_writer :connect_timeout, :send_timeout, :receive_timeout,
                 :keep_alive_timeout
@@ -32,9 +32,17 @@ def initialize(options = {})
         merged_options[:host] = "api.pusherapp.com"
       end
 
-      @scheme, @host, @port, @app_id, @key, @secret = merged_options.values_at(
-        :scheme, :host, :port, :app_id, :key, :secret
-      )
+      # TODO: Change host name when finalized
+      merged_options[:notification_host] =
+        options.fetch(:notification_host, "nativepush-cluster1.pusher.com")
+
+      merged_options[:notification_scheme] =
+        options.fetch(:notification_scheme, "https")
+
+      @scheme, @host, @port, @app_id, @key, @secret, @notification_host, @notification_scheme =
+        merged_options.values_at(
+          :scheme, :host, :port, :app_id, :key, :secret, :notification_host, :notification_scheme
+        )
 
       @http_proxy = nil
       self.http_proxy = options[:http_proxy] if options[:http_proxy]
@@ -298,6 +306,25 @@ def trigger_batch_async(*events)
       post_async('/batch_events', trigger_batch_params(events.flatten))
     end
 
+    def notification_client
+      @notification_client ||=
+        NativeNotification::Client.new(@app_id, @notification_host, @notification_scheme, self)
+    end
+
+
+    # Send a push notification
+    #
+    # POST /apps/[app_id]/notifications
+    #
+    # @param interests [Array] An array of interests
+    # @param message [String] Message to send
+    # @param options [Hash] Additional platform specific options
+    #
+    # @return [Hash]
+    def notify(interests, data = {})
+      notification_client.notify(interests, data)
+    end
+
     # Generate the expected response for an authentication endpoint.
     # See http://pusher.com/docs/authenticating_users for details.
     #

lib/pusher/native_notification/client.rb

@@ -0,0 +1,123 @@
+module Pusher
+  module NativeNotification
+    class Client
+      attr_reader :app_id, :host
+
+      API_PREFIX = "customer_api"
+      API_VERSION = "v1"
+      GCM_TTL = 241920
+      RESTRICTED_GCM_PAYLOAD_KEYS = [:to, :registration_ids]
+      WEBHOOK_LEVELS = ["DEBUG", "INFO"]
+
+      def initialize(app_id, host, scheme, pusher_client)
+        @app_id = app_id
+        @host = host
+        @scheme = scheme
+        @pusher_client = pusher_client
+      end
+
+      # Send a notification via the native notifications API
+      def notify(interests, data = {})
+        Request.new(
+          @pusher_client,
+          :post,
+          url("/notifications"),
+          {},
+          payload(interests, data)
+        ).send_sync
+      end
+
+      private
+
+      # TODO: Actual links
+      #
+      # {
+      #   interests: [Array of interests],
+      #   apns: {
+      #     See https://pusher.com/docs/push_notifications/ios/server
+      #   },
+      #   gcm: {
+      #     See https://pusher.com/docs/push_notifications/android/server
+      #   }
+      # }
+      #
+      # @raise [Pusher::Error] if the `apns` or `gcm` key does not exist
+      # @return [String]
+      def payload(interests, data)
+        interests = Array(interests).map(&:to_s)
+
+        raise Pusher::Error, "Too many interests provided" if interests.length > 1
+
+        data = deep_symbolize_keys!(data)
+        validate_payload(data)
+
+        data.merge!(interests: interests)
+
+        MultiJson.encode(data)
+      end
+
+      def url(path = nil)
+        URI.parse("#{@scheme}://#{@host}/#{API_PREFIX}/#{API_VERSION}/apps/#{@app_id}#{path}")
+      end
+
+      # Validate payload
+      # `time_to_live` -> value b/w 0 and 241920
+      # If the `notification` key is provided, ensure
+      # that there is an accompanying `title` and `icon`
+      # field
+      def validate_payload(payload)
+        unless (payload.has_key?(:apns) || payload.has_key?(:gcm))
+          raise Pusher::Error, "GCM or APNS data must be provided"
+        end
+
+        if (gcm_payload = payload[:gcm])
+          # Restricted keys
+          RESTRICTED_GCM_PAYLOAD_KEYS.each { |k| gcm_payload.delete(k) }
+          if (ttl = gcm_payload[:time_to_live])
+
+            if ttl.to_i < 0 || ttl.to_i > GCM_TTL
+              raise Pusher::Error, "Time to live must be between 0 and 241920 (4 weeks)"
+            end
+          end
+
+          # If the notification key is provided
+          # validate the `icon` and `title`keys
+          if (notification = gcm_payload[:notification])
+            notification_title, notification_icon = notification.values_at(:title, :icon)
+
+            if (!notification_title || notification_title.empty?)
+              raise Pusher::Error, "Notification title is a required field"
+            end
+
+            if (!notification_icon || notification_icon.empty?)
+              raise Pusher::Error, "Notification icon is a required field"
+            end
+          end
+        end
+
+        if (webhook_url = payload[:webhook_url])
+          raise Pusher::Error, "Webhook url is invalid" unless webhook_url =~ /\A#{URI::regexp(['http', 'https'])}\z/
+        end
+
+        if (webhook_level = payload[:webhook_level])
+          raise Pusher::Error, "Webhook level cannot be used without a webhook url" if !payload.has_key?(:webhook_url)
+
+          unless WEBHOOK_LEVELS.include?(webhook_level.upcase)
+            raise Pusher::Error, "Webhook level must either be INFO or DEBUG"
+          end
+        end
+      end
+
+      # Symbolize all keys in the hash recursively
+      def deep_symbolize_keys!(hash)
+        hash.keys.each do |k|
+          ks = k.respond_to?(:to_sym) ? k.to_sym : k
+          hash[ks] = hash.delete(k)
+          deep_symbolize_keys!(hash[ks]) if hash[ks].kind_of?(Hash)
+        end
+
+        hash
+      end
+    end
+  end
+end

pusher.gemspec

@@ -18,9 +18,9 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rspec", "~> 3.0"
   s.add_development_dependency "webmock"
   s.add_development_dependency "em-http-request", "~> 1.1.0"
-  s.add_development_dependency "rake"
-  s.add_development_dependency "rack"
-  s.add_development_dependency "json"
+  s.add_development_dependency "rake", "~> 10.4.2"
+  s.add_development_dependency "rack", "~> 1.6.4"
+  s.add_development_dependency "json", "~> 1.8.3"
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")