Class: Zuck::TargetingSpec

Inherits:
Object
  • Object
show all
Includes:
Helpers
Defined in:
lib/zuck/facebook/targeting_spec.rb

Overview

Some helpers around https://developers.facebook.com/docs/reference/ads-api/targeting-specs/ Use like this:

> ts = Facebook::TargetingSpec.new(graph, ad_account, interest: 'foo', geo_locations: {countries: ['US']})
> ts.spec
=> {
   :countries => [
     [0] "US"
   ],
    :interests => [
     [0] "foo"
   ]
}
> ts.fetch_reach
=> 12345

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Helpers

#normalize_array, #normalize_countries

Constructor Details

#initialize(graph, ad_account, spec = nil) ⇒ TargetingSpec

Returns a new instance of TargetingSpec.

Parameters:

  • graph (Koala::Facebook::API) —

    The koala graph object to use

  • ad_account (String) —

    The ad account you want to use to query the facebook api

  • spec (Hash) (defaults to: nil) —

    The targeting spec. Supported keys:

    • :countries: Array of uppercase two letter country codes
    • :genders (optional): Can be an array with 2 (female) and 1 (male)
    • :gender (optional): Set it to 'male' or 'female' to autoconfigure the genders array
    • :age_min (optional): In years
    • :age_max (optional): In years
    • :age_class (optional): Set it to young or old to autoconfigure age_min and age_max for people older or younger than 25
    • :locales (optional): [disabled] Array of integers, valid keys are here https://graph.facebook.com/search?type=adlocale&q=en
    • :interests: Array of strings with interests


70
71
72
73
74
75
 
# File 'lib/zuck/facebook/targeting_spec.rb', line 70

def initialize(graph, , spec = nil)
  @validated_interests = {}
  @graph = graph
  @ad_account = "act_#{}".gsub('act_act_', 'act_')
  self.spec = spec
end

Instance Attribute Details

#graph ⇒ Object (readonly)

Returns the value of attribute graph.



54
55
56
 
# File 'lib/zuck/facebook/targeting_spec.rb', line 54

def graph
  @graph
end

#spec ⇒ Object

Returns the value of attribute spec.



54
55
56
 
# File 'lib/zuck/facebook/targeting_spec.rb', line 54

def spec
  @spec
end

Class Method Details

.batch_reaches(graph, ad_account, specs) ⇒ Array<Hash>

Fetches a bunch of reach estimates from facebook at once.

Parameters:

  • graph —

    Koala graph instance

  • specs (Array<Hash>) —

    An array of specs as you would pass to #initialize

Returns:

  • (Array<Hash>) —

    Each spec you passed in as the requests parameter with the [:success] set to true/false and [:reach]/[:error] are filled respectively



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/zuck/facebook/targeting_spec.rb', line 118

def self.batch_reaches(graph, , specs)

  # Make all requests
  reaches = []
  specs.each_slice(50) do |specs_slice|
    reaches += graph.batch do |batch_api|
      specs_slice.each do |spec|
        targeting_spec = Zuck::TargetingSpec.new(batch_api, , spec)
        targeting_spec.fetch_reach
      end
    end
  end

  # Structure results
  result = []
  reaches.each_with_index do |res, i|
    result[i] = specs[i].dup
    if res.class < StandardError
      result[i][:success] = false
      result[i][:error]   = res
    else
      result[i][:success] = true
      result[i][:reach]   = res.with_indifferent_access
    end
  end
  result
end

.fetch_reach(graph, ad_account, options) ⇒ TargetingSpec

Convenience method, parameters are the same as in #initialize

Returns:



148
149
150
151
 
# File 'lib/zuck/facebook/targeting_spec.rb', line 148

def self.fetch_reach(graph, , options)
  ts = Zuck::TargetingSpec.new(graph, , options)
  ts.fetch_reach
end

Instance Method Details

#fetch_reach ⇒ Hash

Returns The reach for the options given in #initialize, see https://developers.facebook.com/docs/reference/ads-api/reachestimate/.

Returns:



85
86
87
88
89
90
91
92
 
# File 'lib/zuck/facebook/targeting_spec.rb', line 85

def fetch_reach
  validate_spec
  json = @spec.to_json
  o = "#{@ad_account}/reachestimate"
  result = graph.get_object(o, targeting_spec: json)
  return false unless result
  result.with_indifferent_access
end

#validate_interest(interest) ⇒ Object

Validates a single interest from the cache or calls #validate_interests.to validate the interests via facebook's api.

Parameters:

  • interest (String) —

    A single interest

Returns:

  • boolean



105
106
107
108
109
110
111
 
# File 'lib/zuck/facebook/targeting_spec.rb', line 105

def validate_interest(interest)
  if @validated_interests[interest] == nil
    interests = normalize_array([@spec[:interests]] + [interest])
    @validated_interests = Zuck::AdInterest.validate(@graph, interests)
  end
  @validated_interests[interest] == true
end

#validate_interests ⇒ Object 



94
95
96
97
98
 
# File 'lib/zuck/facebook/targeting_spec.rb', line 94

def validate_interests
  @spec[:interests].each do |w|
    raise(InvalidKeywordError, w) unless validate_interest(w)
  end
end