Class Defensio::Client
In: lib/defensio/client.rb
Parent: Object



api_key  [RW] 
owner_url  [RW] 
version  [RW] 

Public Class methods

Create a new Defensio service wrapper.

Required options:

    api_key: Your api key supplied by the Defensio dudes
  owner_url: Your site URL

Optional options:

    version: The version of the Defensio API you wanna use (default: 1.1)


    # File lib/defensio/client.rb, line 85
85:     def initialize(options)
86:       @api_key   = options.delete(:api_key)   || raise(InvalidAPIKey, 'api_key required')
87:       @owner_url = options.delete(:owner_url) || raise(Error, 'owner_url required')
88:       @version   = options.delete(:version)   || '1.1'
90:       @default_params = { :owner_url => @owner_url }
91:     end

Public Instance methods

This action should be invoked upon the publication of an article to announce its existence. The actual content of the article is sent to Defensio for analysis.

  Parameter             Description                             Possible Values
  article_author        the name of the author of the article   any string
  article_author_email  the email address of the person posting valid email
                        the article
  article_title         the title of the article                string
  article_content       the content of the blog posting itself  text
  permalink             the permalink of the article just       valid URL


     # File lib/defensio/client.rb, line 110
110:     def announce_article(params)
111:       call :announce_article, Response, params
112:     end

This central action determines not only whether Defensio thinks a comment is spam or not, but also a measure of its "spaminess", i.e. its relative likelihood of being spam.

It should be noted that one of Defensio‘s key features is its ability to rank spam according to how "spammy" it appears to be. In order to make the most of the Defensio system in their applications, developers should take advantage of the spaminess value returned by this function, to build interfaces that make it easy for the user to quickly sort through and manage their spamboxes

  Parameter             Description                             Possible Values
  user_ip               the IP address of whomever is posting
                        the comment
  article_date          the date the original blog article      yyyy/mm/dd
                        was posted
  comment_author        the name of the author of the comment       any string
  comment_type          the type of the comment being posted    comment, trackback,
                        to the blog                             pingback, other

Optional parameters:

  Parameter             Description                             Possible Values
  comment_content       the actual content of the comment       text
  comment_author_email  the email address of the person         email address
                        posting the comment
  comment_author_url    the URL of the person posting the       valid URL
  permalink             the permalink of the blog post to which valid URL
                        the comment is being posted
  referrer              the URL of the site that brought        valid URL
                        commenter to this page
  user_logged_in        whether or not the user posting the     true or false
                        comment is logged-into the blogging
  trusted_user          whether or not the user is an           true or false
                        administrator, moderator or editor of
                        this blog; the client should pass true
                        only if blogging platform can guarantee
                        that the user has been authenticated and
                        has a role of responsibility on this
  test_force            FOR TESTING PURPOSES ONLY:              "spam,x.xxxx"
                        use this parameter to force the outcome "ham,x.xxxx"
                        of audit-comment . optionally affix
                        (with a comma) a desired spaminess
                        return value (in the range 0 to 1).

Returned response object will contain: signature, spam and spaminess


     # File lib/defensio/client.rb, line 163
163:     def audit_comment(params)
164:       call :audit_comment, AuditCommentResponse, params
165:     end

This action returns basic statistics regarding the performance of Defensio since activation.


     # File lib/defensio/client.rb, line 201
201:     def get_stats
202:       call :get_stats, StatsResponse
203:     end

This action is used to retrain false negatives. That is to say, to indicate to the filter that comments originally tagged as "ham" (i.e. legitimate) were in fact spam.

Retraining the filter in this manner contributes to a personalized learning effect on the filtering algorithm that will improve accuracy for each user over time.

  Parameter             Description                             Possible Values
  signatures            list of signatures (may contain a       comma-separated
                        single entry) of the comments to be     list of alphanumeric
                        submitted for retraining. note that a   strings
                        signature for each comment was
                        originally provided by Defensio's
                        audit-comment action.


     # File lib/defensio/client.rb, line 182
182:     def report_false_negatives(params)
183:       call :report_false_negatives, Response, params
184:     end

This action is used to retrain false positives. That is to say, to indicate to the filter that comments originally tagged as spam were in fact "ham" (i.e. legitimate comments).

Retraining the filter in this manner contributes to a personalized learning effect on the filtering algorithm that will improve accuracy for each user over time.

Same parameters as report_false_negatives


     # File lib/defensio/client.rb, line 195
195:     def report_false_positives(params)
196:       call :report_false_positives, Response, params
197:     end

This action verifies that the key is valid for the owner calling the service.


    # File lib/defensio/client.rb, line 94
94:     def validate_key
95:       call :validate_key, Response
96:     end

Protected Instance methods


     # File lib/defensio/client.rb, line 217
217:       def call(action, response_class, params={})
218:         RAILS_DEFAULT_LOGGER.debug "[DEFENSIO] #{action} #{params.inspect}"
219: post(convert_name(action), convert_params(@default_params.merge(params)))
220:       end


     # File lib/defensio/client.rb, line 206
206:       def convert_name(name)
207:'_', '-')
208:       end


     # File lib/defensio/client.rb, line 210
210:       def convert_params(params)
211:         params.inject({}) do |hash, (param, value)|
212:           hash[convert_name(param)] = value
213:           hash
214:         end
215:       end


     # File lib/defensio/client.rb, line 222
222:       def post(action, params={})
223:         Net::HTTP.post_form(URI.parse("{@version}/#{action}/#{@api_key}.yaml"), params).body
224:       end