Class: Sift::Client

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/sift/client.rb

Overview

This class wraps accesses through the API

Constant Summary collapse

API_ENDPOINT = 
"https://api.siftscience.com"
API_TIMEOUT = 
2

Instance Method Summary collapse

Constructor Details

#initialize(api_key = Sift.api_key, path = Sift.current_rest_api_path, timeout = API_TIMEOUT) ⇒ Client

Constructor

Parameters:

api_key

The Sift Science API key associated with your customer . This parameter
cannot be nil or blank.

path

The path to the event API, e.g., "/v201/events"



85
86
87
88
89
90
91
92
93
 
# File 'lib/sift/client.rb', line 85

def initialize(api_key = Sift.api_key, path = Sift.current_rest_api_path, timeout = API_TIMEOUT)
  raise("api_key must be a non-empty string") if !api_key.is_a?(String) || api_key.empty?
  raise("path must be a non-empty string") if !path.is_a?(String) || path.empty?
  @api_key = api_key
  @path = path
  @timeout = timeout


end

Instance Method Details

#api_key ⇒ Object 



95
96
97
 
# File 'lib/sift/client.rb', line 95

def api_key
  @api_key
end

#label(user_id, properties = {}, timeout = nil, api_key = @api_key) ⇒ Object

Labels a user as either good or bad. This call is blocking.

Parameters:

user_id

A user's id. This id should be the same as the user_id used in
event calls.

properties

A hash of name-value pairs that specify the label attributes.
This parameter must be specified.

timeout (optional)

The number of seconds to wait before failing the request. By default this is
configured to 2 seconds (see above). This parameter is optional.

Returns:

A Response object is returned and captures the status message and
status code. In general, you can ignore the returned result, though.



213
214
215
216
217
218
219
220
221
 
# File 'lib/sift/client.rb', line 213

def label(user_id, properties = {}, timeout = nil, api_key = @api_key)

  raise("user_id must be a non-empty string") if (!user_id.is_a? String) || user_id.to_s.empty?

  path = Sift.current_users_label_api_path(user_id)

  # No return_action logic supported when using labels.
  track("$label", delete_nils(properties), timeout, path, false, api_key, false)
end

#score(user_id, timeout = nil, api_key = @api_key) ⇒ Object

Retrieves a user’s fraud score from the Sift Science API. This call is blocking.

Parameters:

user_id

A user's id. This id should be the same as the user_id used in
event calls.

Returns:

A Response object is returned and captures the status message and
status code. In general, you can ignore the returned result, though.



180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/sift/client.rb', line 180

def score(user_id, timeout = nil, api_key = @api_key)

  raise("user_id must be a non-empty string") if (!user_id.is_a? String) || user_id.to_s.empty?
  raise("Bad api_key parameter") if api_key.empty?
  timetout ||= @timeout

  options = { :headers => {"User-Agent" => user_agent} }
  options.merge!(:timeout => timeout) unless timeout.nil?

  response = self.class.get("/v#{API_VERSION}/score/#{user_id}/?api_key=#{api_key}", options)
  Response.new(response.body, response.code, response.response)

end

#track(event, properties = {}, timeout = nil, path = nil, return_score = false, api_key = @api_key, return_action = false) ⇒ Object

Tracks an event and associated properties through the Sift Science API. This call is blocking.

Parameters:

event

The name of the event to send. This can be either a reserved event name, like
$transaction or $label or a custom event name (that does not start with a $).
This parameter must be specified.

properties

A hash of name-value pairs that specify the event-specific attributes to track.
This parameter must be specified.

timeout (optional)

The number of seconds to wait before failing the request. By default this is
configured to 2 seconds (see above). This parameter is optional.

path (optional)

Overrides the default API path with a different URL.

return_score (optional)

Whether the API response should include a score for this user. The score will
be calculated using the submitted event.  This feature must be
enabled for your  in order to use it.  Please contact
support@siftscience.com if you are interested in using this feature.

return_action (optional)

Whether the API response should include an action triggered for this transaction.

Returns:

In the case of an HTTP error (timeout, broken connection, etc.), this
method returns nil; otherwise, a Response object is returned and captures
the status message and status code. In general, you can ignore the returned
result, though.



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/sift/client.rb', line 138

def track(event, properties = {}, timeout = nil, path = nil, return_score = false, api_key = @api_key, return_action = false)
  warn "[WARNING] api_key cannot be empty, fallback to default api_key." if api_key.to_s.empty?
  api_key ||= @api_key
  raise("event must be a non-empty string") if (!event.is_a? String) || event.empty?
  raise("properties cannot be empty") if properties.empty?
  raise("Bad api_key parameter") if api_key.empty?
  path ||= @path
  timeout ||= @timeout

  uri = URI.parse(API_ENDPOINT)      
  uri.query = URI.encode_www_form(URI.decode_www_form(uri.query.to_s) << ["return_score", "true"]) if return_score
  uri.query = URI.encode_www_form(URI.decode_www_form(uri.query.to_s) << ["return_action", "true"]) if return_action
  path = path + "?" + uri.query if !uri.query.to_s.empty?

  options = {
    :body => MultiJson.dump(delete_nils(properties).merge({"$type" => event,
                                                           "$api_key" => api_key})),
    :headers => {"User-Agent" => user_agent}
  }
  options.merge!(:timeout => timeout) unless timeout.nil?
  begin
    response = self.class.post(path, options)
    Response.new(response.body, response.code, response.response)
  rescue StandardError => e
    Sift.warn("Failed to track event: " + e.to_s)
    Sift.warn(e.backtrace)
    nil
  end
end

#unlabel(user_id, timeout = nil) ⇒ Object

Unlabels a user. This call is blocking.

Parameters:

user_id

A user's id. This id should be the same as the user_id used in
event calls.

timeout (optional)

The number of seconds to wait before failing the request. By default this is
configured to 2 seconds (see above). This parameter is optional.

Returns:

A Response object is returned with only an http code of 204.



237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/sift/client.rb', line 237

def unlabel(user_id, timeout = nil)

  raise("user_id must be a non-empty string") if (!user_id.is_a? String) || user_id.to_s.empty?
  timetout ||= @timeout

  options = { :headers => {"User-Agent" => user_agent} }
  options.merge!(:timeout => timeout) unless timeout.nil?
  path = Sift.current_users_label_api_path(user_id)
  response = self.class.delete(path + "?api_key=#{@api_key}", options)
  Response.new(response.body, response.code, response.response)
end

#user_agent ⇒ Object 



99
100
101
 
# File 'lib/sift/client.rb', line 99

def user_agent
  "SiftScience/v#{API_VERSION} sift-ruby/#{VERSION}"
end