facebookbusiness 0.5.0.2 → 0.5.0.3

data/lib/facebook_ads/ad_objects/server_side/content.rb

@@ -0,0 +1,128 @@
+# Copyright (c) 2017-present, Facebook, Inc. All rights reserved.
+#
+# You are hereby granted a non-exclusive, worldwide, royalty-free license to use,
+# copy, modify, and distribute this software in source code or binary form for use
+# in connection with the web services and APIs provided by Facebook.
+#
+# As with any software that integrates with the Facebook platform, your use of
+# this software is subject to the Facebook Platform Policy
+# [http://developers.facebook.com/policy/]. This copyright notice shall be
+# included in all copies or substantial portions of the software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+module FacebookAds
+  module ServerSide
+    # Content object contains information about the products.
+    class Content
+
+      # Product Id
+      attr_accessor :product_id
+
+      # number of product
+      attr_accessor :quantity
+
+      # Item Price.
+      attr_accessor :item_price
+
+      # Initializes the object
+      # @param [String] product_id
+      # @param [Integer] quantity
+      # @param [Float] item_price
+      def initialize(product_id: nil, quantity: nil, item_price: nil)
+        unless product_id.nil?
+          self.product_id = String(product_id)
+        end
+        unless quantity.nil?
+          self.quantity = Integer(quantity)
+        end
+        unless item_price.nil?
+          self.item_price = Float(item_price)
+        end
+      end
+
+      # build the object using the input hash
+      # @param [Hash] attributes  attributes in the form of hash
+      def build(attributes = {})
+        return unless attributes.is_a?(Hash)
+
+        # convert string to symbol for hash key
+        attributes = attributes.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+
+        if attributes.has_key?(:'product_id')
+          self.product_id = attributes[:'product_id']
+        end
+
+        if attributes.has_key?(:'quantity')
+          self.quantity = attributes[:'quantity']
+        end
+
+        if attributes.has_key?(:'item_price')
+          self.item_price = attributes[:'item_price']
+        end
+      end
+
+      # Checks equality by comparing each attribute.
+      def ==(o)
+        return true if self.equal?(o)
+        self.class == o.class &&
+            product_id == o.product_id &&
+            quantity == o.quantity &&
+            item_price == o.item_price
+      end
+
+      # @see the `==` method
+      def eql?(o)
+        self == o
+      end
+
+      # Calculates hash code according to all attributes.
+      # @return [Fixnum] Hash code
+      def hash
+        [
+            product_id,
+            quantity,
+            item_price
+        ].hash
+      end
+
+
+      # Returns the string representation of the object
+      # @return [String] String presentation of the object
+      def to_s
+        hash = {}
+        unless product_id.nil?
+          hash['product_id'] = product_id
+        end
+        unless quantity.nil?
+          hash['quantity'] = quantity
+        end
+        unless item_price.nil?
+          hash['item_price'] = item_price
+        end
+        hash.to_s
+      end
+
+      # Normalize input fields to server request format.
+      def normalize
+        hash = {}
+        unless product_id.nil?
+          hash['id'] = product_id
+        end
+        unless quantity.nil?
+          hash['quantity'] = quantity
+        end
+        unless item_price.nil?
+          hash['item_price'] = item_price
+        end
+        hash
+      end
+    end
+  end
+end

data/lib/facebook_ads/ad_objects/server_side/custom_data.rb

@@ -0,0 +1,313 @@
+# Copyright (c) 2017-present, Facebook, Inc. All rights reserved.
+#
+# You are hereby granted a non-exclusive, worldwide, royalty-free license to use,
+# copy, modify, and distribute this software in source code or binary form for use
+# in connection with the web services and APIs provided by Facebook.
+#
+# As with any software that integrates with the Facebook platform, your use of
+# this software is subject to the Facebook Platform Policy
+# [http://developers.facebook.com/policy/]. This copyright notice shall be
+# included in all copies or substantial portions of the software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+module FacebookAds
+  module ServerSide
+    # CustomData includes additional business data about the event which is used for ads delivery optimization.
+    class CustomData
+      # A numeric value associated with this event. This could be a monetary value or a value in some other metric.
+      # Example: 142.54.
+      attr_accessor :value
+
+      # The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three digit currency code.
+      # Example: 'usd'.
+      attr_accessor :currency
+
+      # The name of the page or product associated with the event.
+      # Example: 'lettuce'.
+      attr_accessor :content_name
+
+      # The category of the content associated with the event.
+      # Example: 'grocery'
+      attr_accessor :content_category
+
+      # The content IDs associated with the event, such as product SKUs for items in an
+      # AddToCart event: ['ABC123', 'XYZ789']. If content_type is a product, then your content IDs
+      # must be an array with a single string value. Otherwise, this array can contain any number of string values.
+      attr_accessor :content_ids
+
+      # An array of Content objects that contain the product IDs associated with the event
+      # plus information about the products. id, quantity, and item_price are available fields.
+      attr_accessor :contents
+
+      # A String equal to either 'product' or 'product_group'. Set to product if the keys you send content_ids or
+      # contents represent products. Set to product_group if the keys you send in content_ids represent product groups.
+      attr_accessor :content_type
+
+      # The order ID for this transaction as a String.
+      # Example: 'order1234'.
+      attr_accessor :order_id
+
+      # The predicted lifetime value of a conversion event.
+      # Example: 432.12.
+      attr_accessor :predicted_ltv
+
+      # Use only with InitiateCheckout events. The number of items that a user tries to buy during checkout.
+      # Example: 4
+      attr_accessor :num_items
+
+      # Use only with CompleteRegistration events. The status of the registration event, as a String.
+      # Example: 'registered'.
+      attr_accessor :status
+
+
+      # @param [Float] value
+      # @param [String] currency
+      # @param [String] content_name
+      # @param [String] content_category
+      # @param [Array<String>] content_ids
+      # @param [Array<Content>] contents
+      # @param [String] content_type
+      # @param [String] order_id
+      # @param [Float] predicted_ltv
+      # @param [Integer] num_items
+      # @param [String] status
+      def initialize(value: nil,
+                     currency: nil,
+                     content_name: nil,
+                     content_category: nil,
+                     content_ids: nil,
+                     contents: nil,
+                     content_type: nil,
+                     order_id: nil,
+                     predicted_ltv: nil,
+                     num_items: nil,
+                     status: nil)
+
+        unless value.nil?
+          self.value = value
+        end
+        unless currency.nil?
+          self.currency = currency
+        end
+        unless content_name.nil?
+          self.content_name = content_name
+        end
+        unless content_category.nil?
+          self.content_category = content_category
+        end
+        unless content_ids.nil?
+          self.content_ids = content_ids
+        end
+        unless contents.nil?
+          self.contents = contents
+        end
+        unless content_type.nil?
+          self.content_type = content_type
+        end
+        unless order_id.nil?
+          self.order_id = order_id
+        end
+        unless predicted_ltv.nil?
+          self.predicted_ltv = predicted_ltv
+        end
+        unless num_items.nil?
+          self.num_items = num_items
+        end
+        unless status.nil?
+          self.status = status
+        end
+      end
+
+
+      # build the object using the input hash
+      # @param [Hash] attributes  attributes in the form of hash
+      def build(attributes = {})
+        return unless attributes.is_a?(Hash)
+
+        # convert string to symbol for hash key
+        attributes = attributes.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+
+        if attributes.has_key?(:'value')
+          self.value = attributes[:'value']
+        end
+
+        if attributes.has_key?(:'currency')
+          self.currency = attributes[:'currency']
+        end
+
+        if attributes.has_key?(:'content_name')
+          self.content_name = attributes[:'content_name']
+        end
+
+        if attributes.has_key?(:'content_category')
+          self.content_category = attributes[:'content_category']
+        end
+
+        if attributes.has_key?(:'content_ids')
+          if (value = attributes[:'content_ids']).is_a?(Array)
+            self.content_ids = value
+          end
+        end
+
+        if attributes.has_key?(:'contents')
+          if (value = attributes[:'contents']).is_a?(Array)
+            self.contents = value
+          end
+        end
+
+        if attributes.has_key?(:'content_type')
+          self.content_type = attributes[:'content_type']
+        end
+
+        if attributes.has_key?(:'order_id')
+          self.order_id = attributes[:'order_id']
+        end
+
+        if attributes.has_key?(:'predicted_ltv')
+          self.predicted_ltv = attributes[:'predicted_ltv']
+        end
+
+        if attributes.has_key?(:'num_items')
+          self.num_items = attributes[:'num_items']
+        end
+
+        if attributes.has_key?(:'status')
+          self.status = attributes[:'status']
+        end
+      end
+
+      # Checks equality by comparing each attribute.
+      def ==(o)
+        return true if self.equal?(o)
+        self.class == o.class &&
+            value == o.value &&
+            currency == o.currency &&
+            content_name == o.content_name &&
+            content_category == o.content_category &&
+            content_ids == o.content_ids &&
+            contents == o.contents &&
+            content_type == o.content_type &&
+            order_id == o.order_id &&
+            predicted_ltv == o.predicted_ltv &&
+            num_items == o.num_items &&
+            status == o.status
+      end
+
+      # @see the `==` method
+      def eql?(o)
+        self == o
+      end
+
+      # Calculates hash code according to all attributes.
+      # @return [Fixnum] Hash code
+      def hash
+        [
+            value,
+            currency,
+            content_name,
+            content_category,
+            content_ids,
+            contents,
+            content_type,
+            order_id,
+            predicted_ltv,
+            num_items,
+            status
+        ].hash
+      end
+
+      # Returns the string representation of the object
+      # @return [String] String presentation of the object
+      def to_s
+        hash = {}
+        unless value.nil?
+          hash['value'] = value
+        end
+        unless currency.nil?
+          hash['currency'] = currency
+        end
+        unless content_name.nil?
+          hash['content_name'] = content_name
+        end
+        unless content_category.nil?
+          hash['content_category'] = content_category
+        end
+        unless content_ids.nil?
+          hash['content_ids'] = content_ids
+        end
+        unless contents.nil?
+          hash['contents'] = contents.to_s
+        end
+        unless content_type.nil?
+          hash['content_type'] = content_type
+        end
+        unless order_id.nil?
+          hash['order_id'] = order_id
+        end
+        unless predicted_ltv.nil?
+          hash['predicted_ltv'] = predicted_ltv
+        end
+        unless num_items.nil?
+          hash['num_items'] = num_items
+        end
+        unless status.nil?
+          hash['status'] = status
+        end
+        hash.to_s
+      end
+
+
+      # Normalize input fields to server request format.
+      def normalize
+        hash = {}
+        unless value.nil?
+          hash['value'] = value
+        end
+        unless currency.nil?
+          hash['currency'] = FacebookAds::ServerSide::normalize(currency, 'currency')
+        end
+        unless content_name.nil?
+          hash['content_name'] = content_name
+        end
+        unless content_category.nil?
+          hash['content_category'] = content_category
+        end
+        unless content_ids.nil?
+          hash['content_ids'] = content_ids
+        end
+        unless content_type.nil?
+          hash['content_type'] = content_type
+        end
+        unless order_id.nil?
+          hash['order_id'] = order_id
+        end
+        unless predicted_ltv.nil?
+          hash['predicted_ltv'] = predicted_ltv
+        end
+        unless num_items.nil?
+          hash['num_items'] = num_items
+        end
+        unless status.nil?
+          hash['status'] = status
+        end
+
+        unless contents.nil?
+          content_array = []
+          contents.each do |content|
+            content_array.push(content.normalize)
+          end
+          hash['contents'] = content_array
+        end
+        hash
+      end
+
+    end
+  end
+end

data/lib/facebook_ads/ad_objects/server_side/event.rb

@@ -0,0 +1,236 @@
+# Copyright (c) 2017-present, Facebook, Inc. All rights reserved.
+#
+# You are hereby granted a non-exclusive, worldwide, royalty-free license to use,
+# copy, modify, and distribute this software in source code or binary form for use
+# in connection with the web services and APIs provided by Facebook.
+#
+# As with any software that integrates with the Facebook platform, your use of
+# this software is subject to the Facebook Platform Policy
+# [http://developers.facebook.com/policy/]. This copyright notice shall be
+# included in all copies or substantial portions of the software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require_relative './user_data'
+require_relative './custom_data'
+
+module FacebookAds
+  module ServerSide
+
+    # Server Side Event object.
+    class Event
+
+      # A Facebook pixel Standard Event or Custom Event name.
+      # This is used with event_id to determine if events are identical.
+      attr_accessor :event_name
+
+      # A Unix timestamp in seconds indicating when the actual event occurred.
+      attr_accessor :event_time
+
+      # The browser URL where the event happened.
+      attr_accessor :event_source_url
+
+      # A flag that indicates we should not use this event for ads delivery optimization.
+      # If set to true, we only use the event for attribution.
+      attr_accessor :opt_out
+
+      # An ID used by Facebook to deduplicate the same event sent from both server and browser.
+      # This is used with event_name to determine if events are identical.
+      attr_accessor :event_id
+
+      # An Object that contains user data.
+      attr_accessor :user_data
+
+      # An Object that includes additional business data about the event.
+      attr_accessor :custom_data
+
+
+      # @param [String] event_name
+      # @param [int] event_time
+      # @param [String] event_source_url
+      # @param [Boolean] opt_out
+      # @param [String] event_id
+      # @param [FacebookAds::ServerSide::UserData] user_data
+      # @param [FacebookAds::ServerSide::CustomData] custom_data
+      def initialize(event_name: nil,
+                     event_time: nil,
+                     event_source_url: nil,
+                     opt_out: nil,
+                     event_id: nil,
+                     user_data: nil,
+                     custom_data: nil)
+
+        unless event_name.nil?
+          self.event_name = event_name
+        end
+        unless event_time.nil?
+          self.event_time = event_time
+        end
+        unless event_source_url.nil?
+          self.event_source_url = event_source_url
+        end
+        unless opt_out.nil?
+          self.opt_out = opt_out
+        end
+        unless event_id.nil?
+          self.event_id = event_id
+        end
+        unless user_data.nil?
+          self.user_data = user_data
+        end
+        unless custom_data.nil?
+          self.custom_data = custom_data
+        end
+      end
+
+      # build the object using the input hash
+      # @param [Hash] attributes  attributes in the form of hash
+      def build(attributes = {})
+        return unless attributes.is_a?(Hash)
+
+        # convert string to symbol for hash key
+        attributes = attributes.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+
+        if attributes.has_key?(:'event_name')
+          self.event_name = attributes[:'event_name']
+        end
+
+        if attributes.has_key?(:'event_time')
+          self.event_time = attributes[:'event_time']
+        end
+
+        if attributes.has_key?(:'event_source_url')
+          self.event_source_url = attributes[:'event_source_url']
+        end
+
+        if attributes.has_key?(:'opt_out')
+          self.opt_out = attributes[:'opt_out']
+        end
+
+        if attributes.has_key?(:'event_id')
+          self.event_id = attributes[:'event_id']
+        end
+
+        if attributes.has_key?(:'user_data')
+          self.user_data = attributes[:'user_data']
+        end
+
+        if attributes.has_key?(:'custom_data')
+          self.custom_data = attributes[:'custom_data']
+        end
+      end
+
+      # Show invalid properties with the reasons. Usually used together with valid?
+      # @return Array for valid properties with the reasons
+      def list_invalid_properties
+        invalid_properties = Array.new
+        if @event_name.nil?
+          invalid_properties.push('invalid value for "event_name", event_name cannot be nil.')
+        end
+
+        if @event_time.nil?
+          invalid_properties.push('invalid value for "event_time", event_time cannot be nil.')
+        end
+
+        if @user_data.nil?
+          invalid_properties.push('invalid value for "user_data", user_data cannot be nil.')
+        end
+
+        invalid_properties
+      end
+
+      # Check to see if the all the properties in the model are valid
+      # @return true if the model is valid
+      def valid?
+        return false if @event_name.nil?
+        return false if @event_time.nil?
+        return false if @user_data.nil?
+        true
+      end
+
+      # Checks equality by comparing each attribute.
+      def ==(o)
+        return true if self.equal?(o)
+        self.class == o.class &&
+            event_name == o.event_name &&
+            event_time == o.event_time &&
+            event_source_url == o.event_source_url &&
+            opt_out == o.opt_out &&
+            event_id == o.event_id &&
+            user_data == o.user_data &&
+            custom_data == o.custom_data
+      end
+
+      # @see the `==` method
+      def eql?(o)
+        self == o
+      end
+
+      # Calculates hash code according to all attributes.
+      # @return [Fixnum] Hash code
+      def hash
+        [event_name, event_time, event_source_url, opt_out, event_id, user_data, custom_data].hash
+      end
+
+      def to_s
+        hash = {}
+        unless event_name.nil?
+          hash['event_name'] = event_name
+        end
+        unless event_time.nil?
+          hash['event_time'] = event_time
+        end
+        unless event_source_url.nil?
+          hash['event_source_url'] = event_source_url
+        end
+        unless opt_out.nil?
+          hash['opt_out'] = opt_out
+        end
+        unless event_id.nil?
+          hash['event_id'] = event_id
+        end
+        unless user_data.nil?
+          hash['user_data'] = user_data.to_s
+        end
+        unless custom_data.nil?
+          hash['custom_data'] = custom_data.to_s
+        end
+        hash.to_s
+      end
+
+
+      # Normalize input fields to server request format.
+      def normalize
+        hash = {}
+        unless event_name.nil?
+          hash['event_name'] = event_name
+        end
+        unless event_time.nil?
+          hash['event_time'] = event_time
+        end
+        unless event_source_url.nil?
+          hash['event_source_url'] = event_source_url
+        end
+        unless opt_out.nil?
+          hash['opt_out'] = opt_out
+        end
+        unless event_id.nil?
+          hash['event_id'] = event_id
+        end
+        unless user_data.nil?
+          hash['user_data'] = user_data.normalize
+        end
+        unless custom_data.nil?
+          hash['custom_data'] = custom_data.normalize
+        end
+        hash
+      end
+
+    end
+  end
+end