facebookads 0.0.1 → 0.2.9

data/lib/facebook_ads/ad_objects/event_source_group.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.
+
+# FB:AUTOGEN
+
+module FacebookAds
+  # This class is auto-genereated.
+
+  # For any issues or feature requests related to this class, please let us know
+  # on github and we'll fix in our codegen framework. We'll not be able to accept
+  # pull request for this class.
+
+  class EventSourceGroup < AdObject
+
+    field :business, 'Business'
+    field :event_sources, { list: 'ExternalEventSource' }
+    field :id, 'string'
+    field :name, 'string'
+    has_no_delete
+
+    has_edge :shared_accounts do |edge|
+      edge.post 'EventSourceGroup' do |api|
+        api.has_param :accounts, { list: 'string' }
+      end
+    end
+
+  end
+end

data/lib/facebook_ads/ad_objects/external_event_source.rb

@@ -0,0 +1,38 @@
+# 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.
+
+# FB:AUTOGEN
+
+module FacebookAds
+  # This class is auto-genereated.
+
+  # For any issues or feature requests related to this class, please let us know
+  # on github and we'll fix in our codegen framework. We'll not be able to accept
+  # pull request for this class.
+
+  class ExternalEventSource < AdObject
+
+    field :id, 'string'
+    field :name, 'string'
+    field :source_type, 'string'
+    field :external_event_sources, { list: 'string' }
+    has_no_post
+    has_no_delete
+
+  end
+end

data/lib/facebook_ads/ad_objects/flexible_targeting.rb

@@ -0,0 +1,64 @@
+# 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.
+
+# FB:AUTOGEN
+
+module FacebookAds
+  # This class is auto-genereated.
+
+  # For any issues or feature requests related to this class, please let us know
+  # on github and we'll fix in our codegen framework. We'll not be able to accept
+  # pull request for this class.
+
+  class FlexibleTargeting < AdObject
+
+    field :behaviors, { list: 'IDName' }
+    field :college_years, { list: 'int' }
+    field :connections, { list: 'IDName' }
+    field :custom_audiences, { list: 'IDName' }
+    field :education_majors, { list: 'IDName' }
+    field :education_schools, { list: 'IDName' }
+    field :education_statuses, { list: 'int' }
+    field :ethnic_affinity, { list: 'IDName' }
+    field :family_statuses, { list: 'IDName' }
+    field :friends_of_connections, { list: 'IDName' }
+    field :generation, { list: 'IDName' }
+    field :home_ownership, { list: 'IDName' }
+    field :home_type, { list: 'IDName' }
+    field :home_value, { list: 'IDName' }
+    field :household_composition, { list: 'IDName' }
+    field :income, { list: 'IDName' }
+    field :industries, { list: 'IDName' }
+    field :interested_in, { list: 'int' }
+    field :interests, { list: 'IDName' }
+    field :life_events, { list: 'IDName' }
+    field :moms, { list: 'IDName' }
+    field :net_worth, { list: 'IDName' }
+    field :office_type, { list: 'IDName' }
+    field :politics, { list: 'IDName' }
+    field :relationship_statuses, { list: 'int' }
+    field :user_adclusters, { list: 'IDName' }
+    field :work_employers, { list: 'IDName' }
+    field :work_positions, { list: 'IDName' }
+    has_no_id
+    has_no_get
+    has_no_post
+    has_no_delete
+
+  end
+end

data/lib/facebook_ads/ad_objects/funding_source_details.rb

@@ -0,0 +1,39 @@
+# 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.
+
+# FB:AUTOGEN
+
+module FacebookAds
+  # This class is auto-genereated.
+
+  # For any issues or feature requests related to this class, please let us know
+  # on github and we'll fix in our codegen framework. We'll not be able to accept
+  # pull request for this class.
+
+  class FundingSourceDetails < AdObject
+
+    field :coupon, 'FundingSourceDetailsCoupon'
+    field :display_string, 'string'
+    field :id, 'string'
+    field :type, 'int'
+    has_no_get
+    has_no_post
+    has_no_delete
+
+  end
+end

data/lib/facebook_ads/ad_objects/funding_source_details_coupon.rb

@@ -0,0 +1,40 @@
+# 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.
+
+# FB:AUTOGEN
+
+module FacebookAds
+  # This class is auto-genereated.
+
+  # For any issues or feature requests related to this class, please let us know
+  # on github and we'll fix in our codegen framework. We'll not be able to accept
+  # pull request for this class.
+
+  class FundingSourceDetailsCoupon < AdObject
+
+    field :amount, 'int'
+    field :currency, 'string'
+    field :display_amount, 'string'
+    field :expiration, 'datetime'
+    has_no_id
+    has_no_get
+    has_no_post
+    has_no_delete
+
+  end
+end

data/lib/facebook_ads/ad_objects/helpers/custom_audience_helpers.rb

@@ -0,0 +1,170 @@
+# 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 'digest'
+
+module FacebookAds
+  module CustomAudienceHelpers
+    SCHEMAS = %w{
+      UID
+      EMAIL_SHA256
+      PHONE_SHA256
+      MOBILE_ADVERTISER_ID
+    }
+
+    MULTIKEY_SCHEMAS = %w{
+      EXTERN_ID
+      EMAIL
+      PHONE
+      GEN
+      DOBY
+      DOBM
+      DOBD
+      LN
+      FN
+      FI
+      CT
+      ST
+      ZIP
+      MADID
+      COUNTRY
+    }
+
+    SCHEMAS_WITHOUT_HASH = %w{
+      EXTERN_ID
+      MOBILE_ADVERTISER_ID
+    }
+
+    def add_user(data, schema, options = {})
+      self.users.create(prepare_params(data, schema, options))
+    end
+
+    def remove_user(data, schema, options = {})
+      self.users.destroy(prepare_params(data, schema, options))
+    end
+
+    def prepare_params(data,
+                       schema,
+                       app_ids:     nil,
+                       page_ids:    nil,
+                       pre_hashed:  false,
+                       namespace:   nil,
+                       session:     nil,
+                       data_source: nil)
+
+      unless schema.is_a?(Array) || schema.split(',').length > 1
+        # single key
+        schema = schema.upcase
+        unless is_valid_single_key?(schema) || is_combinational_key?(schema)
+          raise InvalidParameterError, "#{schema} is not a valid schema"
+        end
+
+        data = pre_hashed ? data : data.map { |entry| generate_hash(entry, schema)}
+        is_raw = !is_combinational_key?(schema)
+      else
+        # multi key
+        schema = schema.split(',') unless schema.is_a?(Array)
+
+        data = data.map do |row|
+          raise 'Schema size and data size mismatch' if row.length != schema.length
+
+          row.each_with_index.map do |val, idx|
+            pre_hashed ? val : generate_hash(val, schema[idx])
+          end
+        end
+
+        is_raw = !(schema.map { |s| is_combinational_key?(s) }.any?)
+      end
+
+      {
+        payload: {
+          schema: schema,
+          data: data,
+          is_raw: is_raw,
+          app_ids: app_ids,
+          page_ids: page_ids,
+          data_source: data_source,
+        }.compact,
+        namespace: namespace,
+        session: session,
+      }.compact
+    end
+
+    private
+    def is_valid_single_key?(schema)
+      SCHEMAS.include?(schema)
+    end
+
+    def is_raw_schema?(schemas)
+      (schemas - MULTIKEY_SCHEMAS).empty?
+    end
+
+    def generate_hash(data, schema)
+      SCHEMAS_WITHOUT_HASH.include?(schema) ? normalize(data, schema) : hash_sha256(normalize(data, schema))
+    end
+
+    def is_combinational_key?(schema)
+      schema_parts = schema.split('_').map(&:upcase)
+      return false if schema == 'EXTERN_ID' || schema_parts.count <= 1
+      # EXTERN_ID will be safe here since it's can be used as combination key
+
+      (schema_parts - MULTIKEY_SCHEMAS).empty?
+    end
+
+    def normalize(data, schema)
+      schema = schema.gsub(/_SHA256$/,'') # remove hash suffix
+      # Data normalization
+      # Refer to https://developers.facebook.com/docs/marketing-api/audiences-api for rules
+
+      case schema
+        when 'EMAIL'
+          data.to_s.strip.downcase
+        when 'PHONE'
+          data.to_s.gsub(/[^0-9]/,'')
+        when 'GEN'
+          # Match the first F or M character
+          data.to_s[/[mfMF]/] || (raise InvalidParameterError, "Invalid value: #{data} for Gender")
+        when 'DOBY'
+          data.to_s.strip.gsub(/[^0-9]/,'')
+        when 'DOBM','DOBD'
+          data.to_s.strip.gsub(/[^0-9]/,'').rjust(2,'0')
+        when 'LN', 'FN'
+          data.to_s.strip.gsub(/[^[:alpha:]]/,'').downcase # using [:alpha] here to include also Unicode
+        when 'FI'
+          data.to_s.strip[0].downcase
+        when 'ST', 'CT'
+          data.to_s.strip.downcase.gsub(/[^a-z]+/,'')
+        when 'ZIP'
+          data.to_s.split('-').first.strip.gsub(/[:blank:]+/,'').downcase
+        when 'MADID'
+          data.to_s.downcase
+        when 'COUNTRY'
+          if data.strip.length != 2
+            raise InvalidParameterError, "Only 2-letter country codes is accepted for COUNTRY"
+          end
+          data.strip.downcase
+        else # UID, EXTERN_ID, MOBILE_ADVERTISER_ID
+          data
+      end
+    end
+
+    def hash_sha256(data)
+      Digest::SHA256.hexdigest(data)
+    end
+  end
+end

data/lib/facebook_ads/ad_objects/hotel.rb

@@ -0,0 +1,61 @@
+# 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.
+
+# FB:AUTOGEN
+
+module FacebookAds
+  # This class is auto-genereated.
+
+  # For any issues or feature requests related to this class, please let us know
+  # on github and we'll fix in our codegen framework. We'll not be able to accept
+  # pull request for this class.
+
+  class Hotel < AdObject
+
+    field :address, 'string'
+    field :applinks, 'AppLinks'
+    field :brand, 'string'
+    field :description, 'string'
+    field :guest_ratings, 'string'
+    field :hotel_id, 'string'
+    field :id, 'string'
+    field :images, { list: 'string' }
+    field :lowest_base_price, 'string'
+    field :name, 'string'
+    field :phone, 'string'
+    field :star_rating, 'string'
+    field :url, 'string'
+
+    has_edge :hotel_rooms do |edge|
+      edge.post 'HotelRoom' do |api|
+        api.has_param :applinks, 'object'
+        api.has_param :base_price, 'double'
+        api.has_param :currency, 'string'
+        api.has_param :description, 'string'
+        api.has_param :images, { list: 'object' }
+        api.has_param :margin_level, 'int'
+        api.has_param :name, 'string'
+        api.has_param :pricing_variables, { list: 'object' }
+        api.has_param :room_id, 'string'
+        api.has_param :sale_price, 'double'
+        api.has_param :url, 'string'
+      end
+    end
+
+  end
+end