bonio-facebookbusiness 0.13.0.0

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

@@ -0,0 +1,324 @@
+# 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
+
+      # This ID can be any unique string chosen by the advertiser.
+      # event_id is used to deduplicate events sent by both Facebook Pixel and
+      # Server-Side API. event_name is also used in the deduplication process.
+      # For deduplication, the eventID from Facebook pixel must match the
+      # event_id in the corresponding Server-Side API event.
+      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
+
+      # Processing options you would like to enable for a specific event.
+      # For more details see https://developers.facebook.com/docs/marketing-apis/data-processing-options
+      attr_accessor :data_processing_options
+
+      # A country that you want to associate to this data processing option
+      # For more details see https://developers.facebook.com/docs/marketing-apis/data-processing-options
+      attr_accessor :data_processing_options_country
+
+      # A state that you want to associate with this data processing option.
+      # For more details see https://developers.facebook.com/docs/marketing-apis/data-processing-options
+      attr_accessor :data_processing_options_state
+
+      # Where the conversion occurred.
+      attr_accessor :action_source
+
+      # @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
+      # @param [Array<String>] data_processing_options
+      # @param [int] data_processing_options_country
+      # @param [int] data_processing_options_state
+      # @param String action_source
+      def initialize(event_name: nil,
+                     event_time: nil,
+                     event_source_url: nil,
+                     opt_out: nil,
+                     event_id: nil,
+                     user_data: nil,
+                     custom_data: nil,
+                     data_processing_options: nil,
+                     data_processing_options_country: nil,
+                     data_processing_options_state: nil,
+                     action_source: 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
+        unless data_processing_options.nil?
+          self.data_processing_options = data_processing_options
+        end
+        unless data_processing_options_country.nil?
+          self.data_processing_options_country = data_processing_options_country
+        end
+        unless data_processing_options_state.nil?
+          self.data_processing_options_state = data_processing_options_state
+        end
+        unless action_source.nil?
+          self.action_source = action_source
+        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
+
+        if attributes.has_key?(:'data_processing_options')
+          self.data_processing_options = attributes[:'data_processing_options']
+        end
+
+        if attributes.has_key?(:'data_processing_options_country')
+          self.data_processing_options_country = attributes[:'data_processing_options_country']
+        end
+
+        if attributes.has_key?(:'data_processing_options_state')
+          self.data_processing_options_state = attributes[:'data_processing_options_state']
+        end
+
+        if attributes.has_key?(:'action_source')
+          self.action_source = attributes[:'action_source']
+        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 &&
+            data_processing_options == o.data_processing_options &&
+            data_processing_options_country == o.data_processing_options_country &&
+            data_processing_options_state == o.data_processing_options_state &&
+            action_source == o.action_source
+      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,
+          data_processing_options, data_processing_options_country, data_processing_options_state,
+          action_source,
+        ].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
+        unless data_processing_options.nil?
+          hash['data_processing_options'] = data_processing_options.to_s
+        end
+        unless data_processing_options_country.nil?
+          hash['data_processing_options_country'] = data_processing_options_country.to_s
+        end
+        unless data_processing_options_state.nil?
+          hash['data_processing_options_state'] = data_processing_options_state.to_s
+        end
+        unless action_source.nil?
+          hash['action_source'] = action_source
+        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
+        unless data_processing_options.nil?
+          hash['data_processing_options'] = data_processing_options
+        end
+        unless data_processing_options_country.nil?
+          hash['data_processing_options_country'] = data_processing_options_country
+        end
+        unless data_processing_options_state.nil?
+          hash['data_processing_options_state'] = data_processing_options_state
+        end
+        unless action_source.nil?
+          hash['action_source'] = FacebookAds::ServerSide::Util.normalize(
+            action_source,
+            'action_source'
+          )
+        end
+        hash
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,296 @@
+# 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 'json'
+
+require_relative './event'
+require_relative './event_response'
+
+module FacebookAds
+  module ServerSide
+    class EventRequest
+      # An array of Server Event objects
+      attr_accessor :events
+
+      # Code used to verify that your server events are received correctly by Facebook.
+      # Use this code to test your server events in the Test Events feature in Events Manager. See Test Events Tool
+      # (https://developers.facebook.com/docs/marketing-api/facebook-pixel/server-side-api/using-the-api#testEvents)
+      # for an example.
+      attr_accessor :test_event_code
+
+      # Ad pixel id
+      attr_accessor :pixel_id
+
+      # Platform from which the event is sent e.g. wordpress
+      attr_accessor :partner_agent
+
+      # Scope used to resolve extern_id or Third-party ID. Can be another data set or data partner ID.
+      attr_accessor :namespace_id
+
+      # Unique id used to denote the current set being uploaded.
+      attr_accessor :upload_id
+
+      # Tag string added to track your Offline event uploads.
+      attr_accessor :upload_tag
+
+      # The origin/source of data for the dataset to be uploaded.
+      attr_accessor :upload_source
+
+      # The HttpServiceInterface client to use for executing the request.
+      attr_accessor :http_service_client
+
+      # @param [String] pixel_id
+      # @param [Array(FacebookAds::ServerSide::Event)] events
+      # @param [String] test_event_code
+      # @param [String] partner_agent
+      # @param [String] namespace_id
+      # @param [String] upload_id
+      # @param [String] upload_tag
+      # @param [String] upload_source
+      # @param [HttpServiceInterface] http_service_client
+      def initialize(pixel_id: nil, events: nil, test_event_code: nil, partner_agent: nil,
+          namespace_id: nil, upload_id: nil, upload_tag: nil, upload_source: nil,
+          http_service_client: nil)
+        unless pixel_id.nil?
+          self.pixel_id = pixel_id
+        end
+        unless events.nil?
+          self.events = events
+        end
+        unless test_event_code.nil?
+          self.test_event_code = test_event_code
+        end
+        unless partner_agent.nil?
+          self.partner_agent = partner_agent
+        end
+        unless namespace_id.nil?
+          self.namespace_id = namespace_id
+        end
+        unless upload_id.nil?
+          self.upload_id = upload_id
+        end
+        unless upload_tag.nil?
+          self.upload_tag = upload_tag
+        end
+        unless upload_source.nil?
+          self.upload_source = upload_source
+        end
+        unless http_service_client.nil?
+          self.http_service_client = http_service_client
+        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?(:'pixel_id')
+          self.pixel_id = attributes[:'pixel_id']
+        end
+
+        if attributes.has_key?(:'events')
+          if (value = attributes[:'events']).is_a?(Array)
+            self.events = value
+          end
+        end
+
+        if attributes.has_key?(:'test_event_code')
+          self.test_event_code = attributes[:'test_event_code']
+        end
+
+        if attributes.has_key?(:'partner_agent')
+          self.partner_agent = attributes[:'partner_agent']
+        end
+
+        if attributes.has_key?(:'namespace_id')
+          self.namespace_id = attributes[:'namespace_id']
+        end
+
+        if attributes.has_key?(:'upload_id')
+          self.upload_id = attributes[:'upload_id']
+        end
+
+        if attributes.has_key?(:'upload_tag')
+          self.upload_tag = attributes[:'upload_tag']
+        end
+
+        if attributes.has_key?(:'upload_source')
+          self.upload_source = attributes[:'upload_source']
+        end
+
+        if attributes.has_key?(:'http_service_client')
+          self.http_service_client = attributes[:'http_service_client']
+        end
+      end
+
+      # Execute request
+      def execute
+        unless valid?
+          raise list_invalid_properties
+        end
+
+        if http_service_client
+          return execute_with_client(http_service_client)
+        end
+        params = get_params()
+        params[:data] = normalize
+        ads_pixel = FacebookAds::AdsPixel.get(pixel_id)
+        response = ads_pixel.events.create(params)
+        json_response_object = JSON.parse(JSON.generate(response), object_class: OpenStruct)
+        FacebookAds::ServerSide::EventResponse.new(
+            events_received: json_response_object.events_received,
+            messages: json_response_object.messages,
+            fbtrace_id: json_response_object.fbtrace_id
+        )
+      end
+
+      def normalize
+        normalized_events = []
+        events.each do |event|
+          normalized_events.push(JSON.generate(event.normalize))
+        end
+        normalized_events
+      end
+
+      def get_params
+        params = {}
+        params[:test_event_code] = test_event_code unless test_event_code.nil?
+        params[:partner_agent] = partner_agent unless partner_agent.nil?
+        params[:namespace_id] = namespace_id unless namespace_id.nil?
+        params[:upload_id] = upload_id unless upload_id.nil?
+        params[:upload_tag] = upload_tag unless upload_tag.nil?
+        params[:upload_source] = upload_source unless upload_source.nil?
+        params
+      end
+
+      def execute_with_client http_client
+        url = [
+          "https://#{FacebookAds::DEFAULT_HOST}",
+          FacebookAds::DEFAULT_API_VERSION,
+          pixel_id,
+          'events',
+        ].join('/')
+        headers = {
+          'User-Agent' => "fbbizsdk-ruby-v#{FacebookAds::VERSION}"
+        }
+        params = get_params
+        params[:data] = events.map(&:normalize)
+        appsecret = FacebookAds.config.app_secret
+        access_token = FacebookAds.config.access_token
+        params[:access_token] = access_token
+        if appsecret
+          params[:appsecret_proof] = FacebookAds::ServerSide::HttpUtil.appsecret_proof(appsecret, access_token)
+        end
+
+        http_client.execute(
+          url,
+          FacebookAds::ServerSide::HttpMethod::POST,
+          headers,
+          params
+        )
+      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 @events.nil?
+          invalid_properties.push('invalid value for "data", 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 @events.nil?
+        true
+      end
+
+      # Checks equality by comparing each attribute.
+      def ==(o)
+        return true if self.equal?(o)
+        self.class == o.class &&
+            pixel_id == o.pixel_id &&
+            events == o.events &&
+            test_event_code == o.test_event_code &&
+            partner_agent == o.partner_agent &&
+            namespace_id == o.namespace_id &&
+            upload_id == o.upload_id &&
+            upload_tag == o.upload_tag &&
+            upload_source == o.upload_source &&
+            http_service_client == o.http_service_client
+      end
+
+      # @see the `==` method
+      def eql?(o)
+        self == o
+      end
+
+      # Calculates hash code according to all attributes.
+      # @return [Fixnum] Hash code
+      def hash
+        [
+          pixel_id,
+          events,
+          test_event_code,
+          partner_agent,
+          namespace_id,
+          upload_id,
+          upload_tag,
+          upload_source,
+          http_service_client,
+        ].hash
+      end
+
+      def to_s
+        hash = {}
+        unless pixel_id.nil?
+          hash['pixel_id'] = pixel_id
+        end
+        unless events.nil?
+          hash['data'] = events
+        end
+        unless test_event_code.nil?
+          hash['test_event_code'] = test_event_code
+        end
+        unless partner_agent.nil?
+          hash['partner_agent'] = partner_agent
+        end
+        unless namespace_id.nil?
+          hash['namespace_id'] = namespace_id
+        end
+        unless upload_id.nil?
+          hash['upload_id'] = upload_id
+        end
+        unless upload_tag.nil?
+          hash['upload_tag'] = upload_tag
+        end
+        unless upload_source.nil?
+          hash['upload_source'] = upload_source
+        end
+        hash.to_s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# 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 'concurrent'
+
+module FacebookAds
+  module ServerSide
+    class EventRequestAsync < EventRequest
+      def execute
+        Concurrent::Promise.execute do
+          super
+        end
+      end
+
+      def clone_without_events
+        FacebookAds::ServerSide::EventRequestAsync.new(
+          pixel_id: pixel_id,
+          test_event_code: test_event_code,
+          partner_agent: partner_agent,
+          namespace_id: namespace_id,
+          upload_id: upload_id,
+          upload_tag: upload_tag,
+          upload_source: upload_source,
+        )
+      end
+    end
+  end
+end