Module: FacebookAds::ServerSide

Defined in:
lib/facebook_ads.rb,
lib/facebook_ads/ad_objects/server_side/util.rb,
lib/facebook_ads/ad_objects/server_side/event.rb,
lib/facebook_ads/ad_objects/server_side/content.rb,
lib/facebook_ads/ad_objects/server_side/user_data.rb,
lib/facebook_ads/ad_objects/server_side/custom_data.rb,
lib/facebook_ads/ad_objects/server_side/event_request.rb,
lib/facebook_ads/ad_objects/server_side/event_response.rb

Defined Under Namespace

Classes: Content, CustomData, Event, EventRequest, EventResponse, UserData

Constant Summary collapse

PHONE_NUMBER_IGNORE_CHAR_SET = 
/[\-\s\(\)]+/
PHONE_NUMBER_DROP_PREFIX_ZEROS = 
/^\+?0{0,2}/
US_PHONE_NUMBER_REGEX = 
/^1\(?\d{3}\)?\d{7}$/
INTL_PHONE_NUMBER_REGEX = 
/^\d{1,4}\(?\d{2,3}\)?\d{4,}$/
EMAIL_REGEX =

RFC 2822 for email format

/\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i

Class Method Summary collapse

Class Method Details

.is_already_hashed?(input) ⇒ TrueClass|FalseClass

Returns representing whether the value is hashed.

Parameters:

  • input (String) —

    Input string that is to be validated

Returns:

  • (TrueClass|FalseClass) —

    representing whether the value is hashed



85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 85

def self.is_already_hashed?(input)

	# We support Md5 and SHA256, and highly recommend users to use SHA256 for hashing PII keys.
	md5_match = /^[a-f0-9]{32}$/.match(input)
    sha256_match = /^[a-f0-9]{64}$/.match(input)

	if md5_match != nil or sha256_match != nil
		return true
	end

	return false
end

.is_international_number?(phone_number) ⇒ TrueClass | FalseClass

Returns boolean value representing if a number is international.

Returns:

  • (TrueClass | FalseClass) —

    boolean value representing if a number is international



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 204

def self.is_international_number?(phone_number)

	# Drop upto 2 leading 0s from the number
	phone_number = phone_number.gsub(PHONE_NUMBER_DROP_PREFIX_ZEROS, '')

	if phone_number.start_with?('0')
		return false;
	end

	if phone_number.start_with?('1') && US_PHONE_NUMBER_REGEX.match(phone_number) != nil
		return false;
	end

	if INTL_PHONE_NUMBER_REGEX.match(phone_number) != nil
		return true;
	end

	return false;
end

.normalize(input, field_type) ⇒ String

Normalizes the input string given the field_type

Parameters:

  • input (String) —

    Input string that needs to be normalized

  • field_type (String) —

    Type/Key for the value provided

Returns:

  • (String) —

    Normalized value for the input and field_type.



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 43

def self.normalize(input, field_type)

	if input.nil? or field_type.nil?
		return nil;
	end

	input = input.strip.downcase

	# If the data is already hashed, we by-pass input normalization
	if FacebookAds::ServerSide::is_already_hashed?(input) == true
		return input
    end

	normalized_input = input;

	case field_type
	when 'country'
		normalized_input = FacebookAds::ServerSide::normalize_country input
	when 'ct'
      normalized_input = FacebookAds::ServerSide::normalize_city input
    when 'currency'
      return FacebookAds::ServerSide::normalize_currency input
	when 'em'
		normalized_input = FacebookAds::ServerSide::normalize_email input
	when 'ge'
		normalized_input = FacebookAds::ServerSide::normalize_gender input
	when 'ph'
		normalized_input = FacebookAds::ServerSide::normalize_phone input
	when 'st'
		normalized_input = FacebookAds::ServerSide::normalize_state input
	when 'zp'
		normalized_input = FacebookAds::ServerSide::normalize_zip input
    end

    normalized_input = FacebookAds::ServerSide::sha256Hash normalized_input

	return normalized_input
end

.normalize_city(city) ⇒ Object

Normalizes the given city and returns acceptable hashed city value



112
113
114
115
116
117
118
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 112

def self.normalize_city(city)

    # Remove commonly occuring characters from city name.
	city = city.gsub(/[0-9.\s\-()]/,'')

	return city
end

.normalize_country(country) ⇒ Object

Normalizes the given country code and returns acceptable hashed country ISO code



99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 99

def self.normalize_country(country)

	# Replace unwanted characters and retain only alpha characters bounded for ISO code.
	country = country.gsub(/[^a-z]/,'')

	if country.length != 2
		raise ArgumentError, "Invalid format for country:'" + country + "'.Please follow ISO 2-letter ISO 3166-1 standard for representing country. eg: us"
	end

	return  country
end

.normalize_currency(currency) ⇒ Object

Normalizes the given currency code and returns acceptable hashed currency ISO code



121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 121

def self.normalize_currency(currency)

	# Retain only alpha characters bounded for ISO code.
	currency = currency.gsub(/[^a-z]/,'')

	if currency.length != 3
		raise ArgumentError, "Invalid format for currency:'" + currency + "'.Please follow ISO 3-letter ISO 4217 standard for representing currency. Eg: usd"
	end

	return currency;
end

.normalize_email(email) ⇒ Object

Normalizes the given email and returns acceptable hashed email value



134
135
136
137
138
139
140
141
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 134

def self.normalize_email(email)

	if EMAIL_REGEX.match(email) == nil
		return ArgumentError, "Invalid email format for the passed email:' + email + '.Please check the passed email format."
	end

	return email
end

.normalize_gender(gender) ⇒ Object

Normalizes the given gender and returns acceptable hashed gender value



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 144

def self.normalize_gender(gender)

    # Replace extra characters with space, to bound under alpha characters set.
    gender = gender.gsub(/[^a-z]/,'')

	case gender
	when 'female' , 'f'
		gender = 'f'
	when 'male' , 'm'
		gender = 'm'
	else
		return nil
	end

	return gender
end

.normalize_phone(phone) ⇒ Object

Normalizes the given phone and returns acceptable hashed phone value



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 162

def self.normalize_phone(phone)

	# Drop the spaces, hyphen and parenthesis from the Phone Number
	normalized_phone = phone.gsub(PHONE_NUMBER_IGNORE_CHAR_SET, '')

	if(FacebookAds::ServerSide::is_international_number?(normalized_phone))
		normalized_phone = normalized_phone.gsub(PHONE_NUMBER_DROP_PREFIX_ZEROS, '')
	end

	if normalized_phone.length < 7 || normalized_phone.length > 15
		return nil;
	end

	return normalized_phone
end

.normalize_state(state) ⇒ Object

Normalizes the given city and returns acceptable hashed city value



179
180
181
182
183
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 179

def self.normalize_state(state)
	state = state.gsub(/[0-9.\s\-()]/,'')

	return state
end

.normalize_zip(zip) ⇒ Object

Normalizes the given zip and returns acceptable hashed zip code value



186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 186

def self.normalize_zip(zip)

	# Remove spaces from the Postal code
	zip = zip.gsub(/[\s]/,'')

    # If the zip code '-', we retain just the first part alone.
	zip = zip.split('-')[0]

	if zip.length < 2
		return nil
	end

	return zip
end

.sha256Hash(input) ⇒ String

Returns SHA 256 hash of input string.

Returns:

  • (String) —

    SHA 256 hash of input string



33
34
35
36
37
 
# File 'lib/facebook_ads/ad_objects/server_side/util.rb', line 33

def self.sha256Hash(input)
	unless input.nil?
		Digest::SHA256.hexdigest input
	end
end