xiaomi-push 0.2.4 → 0.3.0

data/lib/xiaomi/push/services/message.rb

@@ -5,8 +5,15 @@ require 'xiaomi/push/services/messages/android'
 module Xiaomi
   module Push
     module Services
+      # 单条消息类 API
+      #
+      # 允许向单个设备或多个设备发送同样的推送消息
+      #
+      # 设备的标识支持 reg_id/alias/user/topic/topics/all
+      #
+      # @attr [Client] context
       class Message
-
+        # 消息类型模板
         MESSAGE_TYPE = {
           reg_id: {
             uri: 'regid',
@@ -16,6 +23,10 @@ module Xiaomi
             uri: 'alias',
             query: 'alias'
           },
+          user: {
+            uri: 'user_account',
+            query: 'user_account'
+          },
           topic: {
             uri: 'topic',
             query: 'topic'
@@ -35,35 +46,67 @@ module Xiaomi
         }
 
         attr_reader :context
+
         def initialize(context)
           @context = context
         end
 
+        # 推送消息
+        #
+        # @see https://dev.mi.com/console/doc/detail?pId=1163#_0
+        #
+        # @param (see Xiaomi::Push::Message::Base#initialize)
+        # @param [Hash, Message::IOS, Message::Android] options Hash 结构消息体 (详见 {Xiaomi::Push::Message::IOS}, {Message::Android})
+        # @return [Hash] 小米返回数据结构
+        #
+        # @raise [RequestError] 推送消息不满足 reg_id/alias/user/topic/topics/all 会引发异常
         def send(**options)
           type, value = fetch_message_type(options)
           if type && value
             url = @context.build_uri("message/#{type[:uri]}")
             if options[:message].kind_of?Xiaomi::Push::Message::Base
               options[:message].type(type[:query], value)
-              params = options[:message].build
+              params = options[:message].to_params
             else
               params = options[:message]
               params[type[:query].to_sym] = value
             end
 
-            r = RestClient.post url, params, @context.header
-            data = MultiJson.load r
+            @context.post(url, params)
           else
-            raise Xiaomi::Push::RequestError, 'Not match message type: reg_id/alias/topic/topics/all'
+            raise Xiaomi::Push::RequestError, '无效的消息类型，请检查是否符合这些类型: reg_id/alias/topic/topics/all'
           end
         end
 
+        # 获取消息的统计数据
+        #
+        # @example 获取 2017-09-01 到 2017-09-30 应用 com.icyleaf.app.helloworld 统计数据
+        #   counters('20170901', '20170930', 'com.icyleaf.app.helloworld')
+        #
+        # @see https://dev.mi.com/console/doc/detail?pId=1163#_2
+        #
+        # @param [String] start_date 开始日期，格式 yyyyMMdd
+        # @param [String] end_date 结束日期，必须小于 30 天。格式 yyyyMMdd
+        # @param [String] package_name 包名，Android 为 package name，iOS 为 Bundle identifier
+        # @return [Hash] 小米返回数据结构
+        def counters(start_date, end_date, package_name)
+          url = @context.build_uri('stats/message/counters')
+          params = {
+            start_date: start_date,
+            end_date: end_date,
+            restricted_package_name: package_name
+          }
+
+          @context.get(url, params)
+        end
+
         private
 
+        # 获取消息类型
         def fetch_message_type(data)
           type, value = nil
           MESSAGE_TYPE.select do |k,v|
-            if data.has_key?k
+            if data.has_key?(k)
               type = v
               value = data[k]
               break
@@ -72,56 +115,6 @@ module Xiaomi
 
           [type, value]
         end
-
-        def valid?(params)
-          validates = {
-            'payload' => {
-              require: true,
-            },
-            'restricted_package_name' => {
-              require: true,
-            },
-            'pass_through' => {
-              require: true,
-            },
-            'title' => {
-              require: true,
-            },
-            'description' => {
-              require: true,
-            },
-            'notify_type' => {
-              require: true,
-              values: {
-                'DEFAULT_ALL' => -1,
-                'DEFAULT_SOUND' => 1,
-                'DEFAULT_VIBRATE' => 2,
-                'DEFAULT_LIGHTS' => 3
-              }
-            },
-            'time_to_live' => {
-              require: false,
-            },
-            'time_to_send' => {
-              require: false,
-            },
-            'notify_id' => {
-              require: false,
-            },
-            'extra.sound_uri' => {
-              require: false,
-            },
-            'extra.ticker' => {
-              require: false,
-            },
-            'extra.notify_foreground' => {
-              require: false,
-            },
-            'extra.notify_effect' => {
-              require: false,
-            },
-          }
-        end
       end
     end
   end

data/lib/xiaomi/push/services/messages.rb

@@ -0,0 +1,91 @@
+require 'xiaomi/push/services/messages/base'
+require 'xiaomi/push/services/messages/ios'
+require 'xiaomi/push/services/messages/android'
+
+module Xiaomi
+  module Push
+    module Services
+      # 消息类 API
+      #
+      # 允许向多个设备发送不同的推送消息
+      #
+      # 设备的标识支持 reg_id/alias/user_account
+      #
+      # @attr [Client] context
+      class Messages
+        # 消息类型模板
+        MESSAGE_TYPE = {
+          reg_id: {
+            uri: 'regids',
+            keys: [:reg_id, :regid, :registration_id]
+          },
+          alias: {
+            uri: 'aliases',
+            keys: [:alias, :aliass, :aliases]
+          },
+          user: {
+            uri: 'user_accounts',
+            keys: [:user, :account, :useraccount, :user_account]
+          }
+        }
+
+        attr_reader :context
+
+        def initialize(context)
+          @context = context
+        end
+
+        # 推送消息
+        #
+        # @see https://dev.mi.com/console/doc/detail?pId=1163#_1_0
+        #
+        # @param [Hash] type 发送消息类型，可选 :reg_id, :alias, :user
+        # @param [Array] messages 消息结构消息体的数组 (详见 {Xiaomi::Push::Message::IOS}, {Message::Android})
+        # @return [Hash] 小米返回数据结构
+        #
+        # @raise [RequestError] 推送消息不满足 reg_id/alias/user 会引发异常
+        # @raise [RequestError] 消息体没有包含关键 target key 会引发异常
+        # @raise [RequestError] messages 不是数组存储的消息体时会引发异常
+        def send(type, messages = [])
+          url = @context.build_uri("multi_messages/#{request_uri(type)}")
+          params = request_params(type, messages)
+          @context.post(url, params)
+        end
+
+        private
+
+        # 获取消息类型
+        def request_uri(type)
+          MESSAGE_TYPE[type][:uri]
+        rescue NoMethodError
+          raise RequestError, '无效的消息类型，请检查是否符合这些类型: reg_id/alias/user'
+        end
+
+        def request_params(type, messages)
+          raise RequestError, '消息必须是数组类型' unless messages.kind_of?(Array)
+
+          messages.each_with_object([]) do |message, obj|
+            message = options[:message].to_params if message.kind_of?(Xiaomi::Push::Message::Base)
+            target_key = target_key(type, message)
+
+            raise RequestError, "#{type.to_s} 消息缺失关键 Key，可设置为 #{MESSAGE_TYPE[type][:keys].join('/')} 均可：#{message}" unless target_key
+
+            obj.push({
+              target: message.delete(target_key),
+              message: message,
+            })
+          end
+        end
+
+        def target_key(type, message)
+          keys = MESSAGE_TYPE[type][:keys]
+          message.each do |key, _|
+            return key if keys.include?(key)
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/xiaomi/push/services/messages/android.rb

@@ -1,8 +1,18 @@
 module Xiaomi
   module Push
     module Message
+      # Android 消息数据体
+      #
+      # @attr [String] title 标题
+      # @attr [String] description 描述
+      # @attr [String] badge 角标, 默认 1
+      # @attr [String] sound 声音，默认 default
+      # @attr [String] pass_through 是否为穿透, 取值 0(默认，通知栏消息)/1（穿透）
+      # @attr [String] notify_type 提醒类型，取值 DEFAULT_ALL(默认)/DEFAULT_SOUND(提示音)/DEFAULT_VIBRATE(振动)/DEFAULT_LIGHTS(指示灯)
+      # @attr [Integer] notify_id 提醒，默认情况下，通知栏只显示一条推送消息。如果通知栏要显示多条推送消息，需要针对不同的消息设置不同的 notify_id
       class Android < Base
-        attr_accessor :title, :description, :badge, :sound, :pass_through, :notify_type, :notify_id, :extras
+        attr_accessor :title, :description, :badge, :sound, :pass_through, :notify_type, :notify_id
+
         def initialize(**params)
           @title = params[:title]
           @description = params[:description]

data/lib/xiaomi/push/services/messages/base.rb

@@ -1,9 +1,23 @@
 module Xiaomi
   module Push
     module Message
+      # 消息体的基本数据
+      #
+      # @abstract
+      # @attr [String] registration_id reg id
+      # @attr [String] alias 别名
+      # @attr [String] topic 标签
+      # @attr [String] user_account user account
+      # @attr [String] topics 多个标签
+      # @attr [String] topic_op 配合 topics 使用
+      # @attr [String] extras 额外参数
       class Base
-        attr_accessor :registration_id, :alias, :topic, :topics, :topic_op, :extras
+        attr_accessor :registration_id, :alias, :topic, :user_account, :topics, :topic_op, :extras
 
+        # 设置或获取附加数据
+        # @param [String] key
+        # @param [String] value
+        # @return [void]
         def extra(key, value = nil)
           unless value
             @extras[key]
@@ -12,21 +26,35 @@ module Xiaomi
           end
         end
 
+        # 设置或获取基本数据
+        #
+        # @param [String] key 设置 :registration_id, :alias, :topic, :user_account, :topics, :topic_op, :extras
+        # @param [String] value
+        # @return [void]
         def type(key, value = nil)
           key = "@#{key}"
 
           if value
-            instance_variable_set key, value
+            instance_variable_set(key, value)
           else
-            instance_variable_get key
+            instance_variable_get(key)
           end
         end
 
-        def build
+        # 转换为字典
+        # @return [Hash] 消息体
+        def to_params
           hash_data = {}
           instance_variables.each do |ivar|
-            key = ivar.to_s.delete('@', '')
-            value = instance_variable_get ivar
+            key = instance_key(ivar)
+
+            key = if ios? && ios10_struct?
+              ios10_struct(key)
+            else
+              extra_key(key)
+            end
+
+            value = instance_variable_get(ivar)
 
             next unless value
 
@@ -42,6 +70,80 @@ module Xiaomi
 
           hash_data
         end
+
+        # 检查是否为 iOS 10 消息体
+        #
+        # @return [Bool]
+        def ios10_struct?
+          return @ios10_struct unless @ios10_struct.nil?
+
+          @ios10_struct = false
+
+          keys = instance_variables.map {|e| instance_key(e) }
+          %w(title subtitle).each do |key|
+            return @ios10_struct = true if keys.include?(key)
+          end
+
+          @ios10_struct
+        end
+
+        # 转换 iOS 10 消息的参数
+        #
+        # 仅转换 title, subtitle, body 和 description
+        #
+        # @example
+        #   ios10_struct('title') # => 'aps_proper_fields.title'
+        #   ios10_struct('description') # => 'aps_proper_fields.body'
+        #   ios10_struct('badge') # => 'badge'
+        #
+        # @param [String] key
+        # @return [Bool]
+        def ios10_struct(key)
+          key = 'body' if key == 'description'
+          return extra_key(key) unless %w(title subtitle body mutable-content).include?(key)
+
+          "aps_proper_fields.#{key}"
+        end
+
+        # 检测是否是 iOS 消息体
+        #
+        # @return [Bool]
+        def ios?
+          current == 'IOS'
+        end
+
+        # 检测是否是 Android 消息体
+        #
+        # @return [Bool]
+        def android?
+          current == 'ANDROID'
+        end
+
+        # 当前消息体类型
+        #
+        # @return [String] IOS/ANDROID
+        def current
+          @current ||= self.class.name.split('::')[-1].upcase
+        end
+
+        private
+
+        def instance_key(var)
+          var.to_s.gsub('_', '-').delete('@')
+        end
+
+        def extra_key?(key)
+          %w(badge sound category).include?(key)
+        end
+
+        def extra_key(key)
+          if extra_key?(key)
+            key = 'sound_url' if key.include?('sound')
+            key = "extra.#{key}"
+          else
+            key
+          end
+        end
       end
     end
   end

data/lib/xiaomi/push/services/messages/ios.rb

@@ -1,10 +1,30 @@
 module Xiaomi
   module Push
     module Message
+      # iOS 数据消息体
+      # @attr [String] title 标题（仅适用于 iOS 10 以上设备）
+      # @attr [String] subtitle 副标题（仅适用于 iOS 10 以上设备）
+      # @attr [String] body 描述（仅适用于 iOS 10 以上设备）
+      # @attr [Integer] mutable_content 可变内容，默认 nil 不启用
+      # @attr [String] image 图片地址（仅适用于 iOS 10 以上设备，填写后自动启用 mutable_content）
+      # @attr [String] description 描述（如果设置了 title 或 subtitle 将会启用变为 {#body}）
+      # @attr [Integer] badge 角标, 默认 1
+      # @attr [String] sound 声音，默认 default
+      # @attr [String] category iOS 8 以上可设置推送消息快速回复类别
       class IOS < Base
-        attr_accessor :description, :badge, :sound, :category, :extras
+        attr_accessor :title, :subtitle, :body, :mutable_content
+        attr_accessor :description, :badge, :sound, :category
+
         def initialize(**params)
+          @title = params[:title]
+          @subtitle = params[:subtitle]
           @description = params[:description]
+          @body = params[:body] || @description
+
+          @image = params[:image]
+          @mutable_content = params[:mutable_content]
+          @mutable_content = 1 if @image
+
           @badge = params[:badge] || 1
           @sound = params[:sound] || 'default'
           @category = params[:category]

data/lib/xiaomi/push/services/topic.rb

@@ -1,20 +1,57 @@
 module Xiaomi
   module Push
     module Services
+      # 标签类 API
+      #
+      # @attr [Client] context
       class Topic
         attr_reader :context
+
+        # 初始化
+        #
+        # @param [Client] context
         def initialize(context)
           @context = context
         end
 
+        # 订阅标签
+        #
+        # 可使用 reg id 或 alias 的方式订阅标签
+        #
+        # @example
+        #   subscribe(reg_id: 'abc', topic: 'beijing')
+        #   subscribe(alias: 'abc', topic: 'beijing')
+        #   subscribe(alias: 'abc,def,ghi,jkl', topic: 'beijing')
+        #
+        # @param [Hash] options
+        # @option options [String] :reg_id 订阅 reg id，多个以逗号分割，最多 1000 个
+        # @option options [String] :aliases 订阅 alias，多个以逗号分割，最多 1000 个
+        # @option options [String] :topic 订阅名
+        # @option options [String] :category 分类，可选项
+        # @return [Hash] 小米返回数据结构
         def subscribe(**options)
           url, params = prepare_params(__method__.to_s, options)
-          @context.request url, params
+          @context.post(url, params)
         end
 
+        # 取消订阅标签
+        #
+        # 可使用 reg id 或 alias 的方式取消订阅标签
+        #
+        # @example
+        #   unsubscribe(reg_id: 'abc', topic: 'beijing')
+        #   unsubscribe(alias: 'abc', topic: 'beijing')
+        #   unsubscribe(alias: 'abc,def,ghi,jkl', topic: 'beijing')
+        #
+        # @param [Hash] options
+        # @option options [String] :reg_id 订阅 reg id，多个以逗号分割，最多 1000 个
+        # @option options [String] :aliases 订阅 alias，多个以逗号分割，最多 1000 个
+        # @option options [String] :topic 订阅名
+        # @option options [String] :category 分类，可选项
+        # @return [Hash] 小米返回数据结构
         def unsubscribe(**options)
           url, params = prepare_params(__method__.to_s, options)
-          @context.request url, params
+          @context.post(url, params)
         end
 
         private