bluekai 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 68f6e5115ea82ddcda1d0ad4780f27fd0b33d73e
+  data.tar.gz: acd51bbeef54aac2ce754571fbb6fe3cd592707a
+SHA512:
+  metadata.gz: 8460428509ffdac8f0b0994f4be95fa89982e967d67d7342a5b9a796729e6672f2aa879e1b247798b65a8afabff27be2e3f757da0e4b8a97fd76127c44843b80
+  data.tar.gz: e35bbd450af7dc97de6489f679c8fbfa6415e483d967dcb322088d49db60f757a816aa42ccf98276588d64588fc8b4226ea1a46dcc32ec59d1a7c631ee8a6b72

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.env

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.2.0

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+
+group :development, :test do
+  gem 'rubocop-ci', github: 'ad2games/rubocop-ci'
+  gem "codeclimate-test-reporter", group: :test, require: nil
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 ad2games GmbH
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission 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.

data/README.md

@@ -0,0 +1,44 @@
+# Bluekai
+[![Gem Version](http://img.shields.io/gem/v/bluekai.svg)](http://rubygems.org/gems/bluekai)
+[![Circle CI](https://circleci.com/gh/ad2games/bluekai.png?style=shield&circle-token=323d6ce1376f1473cab4474d89f8fc7287446595)](https://circleci.com/gh/ad2games/bluekai)
+[![Code Climate](https://codeclimate.com/repos/5523e6d8695680516e00144d/badges/40648ea53c768dd15de5/gpa.svg)](https://codeclimate.com/repos/5523e6d8695680516e00144d/feed)
+[![Test Coverage](https://codeclimate.com/repos/5523e6d8695680516e00144d/badges/40648ea53c768dd15de5/coverage.svg)](https://codeclimate.com/repos/5523e6d8695680516e00144d/feed)
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bluekai'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bluekai
+
+## Usage
+
+Before you start, please ensure the following variables are correctly set in your environment: `ENV['BLUEKAI_DOMAIN']`, `ENV['BLUEKAI_API_USER_KEY']`, `ENV['BLUEKAI_API_PRIVATE_KEY']` and `ENV['BLUEKAI_PARTNER_ID']`
+
+
+List all self-classification categories
+```ruby
+   Bluekai::Client.new.category_list({})
+```
+Read category parameters including estimated reach (estimated number of unique users
+based on 30-day inventory) on desktop
+
+```ruby
+  Bluekai::Client.new.category_read({category_id: 421426, stats: 'true', device_type: 'desktop'})
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/bluekai/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler/gem_tasks'
+require 'rubocop-ci'

data/bluekai.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bluekai/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bluekai"
+  spec.version       = Bluekai::VERSION
+  spec.authors       = ["ad2games GmbH"]
+  spec.email         = ["developers@ad2games.com"]
+  spec.summary       = "Simple client for the BlueKai API"
+  spec.description   = "Simple client for the BlueKai API (services.bluekai.com)"
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'httparty'
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'vcr'
+  spec.add_development_dependency 'webmock'
+  spec.add_development_dependency 'rspec'
+end

data/circle.yml

@@ -0,0 +1,3 @@
+test:
+  pre:
+    - bundle exec rake rubocop

data/lib/bluekai.rb

@@ -0,0 +1,7 @@
+require 'bluekai/version'
+require 'bluekai/client'
+require 'bluekai/error'
+
+module Bluekai
+  # Your code goes here...
+end

data/lib/bluekai/client.rb

@@ -0,0 +1,407 @@
+require 'openssl'
+require 'base64'
+require 'httparty'
+require 'cgi'
+
+module Bluekai
+  # A simple BlueKai client
+  class Client
+    attr_reader :domain, :api_user_key
+
+    def initialize(opts = {})
+      @domain = opts.fetch(:domain, ENV['BLUEKAI_DOMAIN']) ||
+        fail(Error, 'BlueKai domain missing')
+      @api_user_key = opts.fetch(:api_user_key, ENV['BLUEKAI_API_USER_KEY']) ||
+        fail(Error, 'BlueKai API user key missing')
+      @api_private_key = opts.fetch(:api_private_key, ENV['BLUEKAI_API_PRIVATE_KEY']) ||
+        fail(Error, 'BlueKai API private key missing')
+      @partner_id = opts.fetch(:partner_id, ENV['BLUEKAI_PARTNER_ID']) ||
+        fail(Error, 'BlueKai PartnerID missing')
+      @opts = opts
+    end
+
+    def ping
+      request('GET', '/Services/WS/Ping', {}).to_i == 200 rescue false
+    end
+
+    # Public: Lists categories in the BlueKai taxonomy. API definition
+    # can be found here https://kb.bluekai.com/display/PD/Taxonomy+API
+    #
+    # parentId - integer
+    # fullPath - {0,1}
+    # bkSize - {0,1} Enter 1 to include the inventory of unique users in
+    #          the BlueKai network for each category.
+    # intlDataCountryId - {-1..24} for country index see
+    #                     (https://kb.bluekai.com/display/PD/Taxonomy+API)
+    # device_code - {0 = Desktop + Mobile,1 = Desktop, 2 = Mobile}
+    # showBuyable - {0,1}
+    # showLeafStatus - {0,1}
+    # description - {0,1}
+    # vertical - {0,1}
+    # showReceivedAudienceCategories - {0,1}
+    # showCategoryPriceAtDate - {'YYYY-MM-DD'}
+    #
+    # Returns array of taxonomy nodes.
+    def taxonomy(query = {})
+      request('GET', '/Services/WS/Taxonomy', query)[:nodeList]
+    end
+
+    ####
+    #### Categories
+    ####
+    #### API definition can be found here
+    #### https://kb.bluekai.com/display/PD/Self-Classification+Category+API
+    ####
+
+    # Public: Lists self classification categories in private taxonomy
+    #
+    # name:string - Returns all self-classification categories based on the specified
+    #               name (whole or partial). The name is case-insensitive.
+    #
+    # offset:integer - Specify the starting index from which to return
+    #                  the self-classification categories.
+    #
+    # size:integer - Specifies the maximum number of categories to be included in
+    #                the response. This filter requires the offset filter to be specified.
+    #
+    # parent_id:integer - Returns all self-classification categories
+    #                     based on the ID of the specified parent category.
+    #
+    # sort_by:string - Enter 'name' or 'id' to sort the returned self-classification categories in
+    #                  alphabetical or numerical order (based on categoryId)
+    #
+    # sorting_order:string - Enter 'asc' or 'desc' to list the returned
+    #                        self-classification categories in ascending
+    #                        or descending order based on the category
+    #                        name or categoryId.
+    #
+    # Returns array of category hashes
+    def category_list(query = {})
+      query = { sort_by: 'name',
+                sorting_order: 'asc' }.merge(query)
+      request('GET', '/Services/WS/classificationCategories', query)[:categories]
+    end
+
+    # Public: returns the self-classification category
+    #         specified by the category_id
+    #
+    # category_id:integer - MANDATORY The unique ID assigned to the
+    #                       self-classification category to be retrieved
+    #
+    # stats:string - {'True','False'} Returns the reach (estimated
+    #                 number of unique users based on 30-day
+    #                 inventory) for the self-classification category.
+    #
+    # device_type:string - reach for the self-classification category
+    #                      based on the specified device, which may either
+    #                      be 'all', 'desktop', or 'mobile'
+    #
+    # intl_code - returns the reach for the self-classification category
+    #             based on the specified country. The default country
+    #             is ALL. You may enter one of the following country
+    #             codes: ALL, US, AU, CA, GB, GER, ESP, NL, MX, IT,
+    #             FR, BR, AR, RU, NZ, JP, CL, CN.
+    #
+    # Returns: A hash of Bluekai private category data
+    def category_read(query)
+      fail 'no category_id found in hash' unless query.key?(:category_id)
+      category_id = query.delete(:category_id)
+      request('GET', "/Services/WS/classificationCategories/#{category_id}", query)
+    end
+
+    # Public: Creates a new self-classification category
+    #
+    # name:string - Name of the self-classification category
+    #
+    # parent_id:integer - Unique ID of the parent node for the
+    #                     self-classification category.
+    #
+    # description:string - Description of uUser attribute
+    #                      represented by this category.
+    #
+    # analytics_excluded:string - {'True','False'} Specify whether the
+    #                   self-classification category is to be excluded
+    #                   from Audience Analytics reports. This property
+    #                   is false by default.
+    #
+    # navigation_only:string - {'True','False'} Specify whether the
+    #                          self-classification category functions
+    #                          exclusively as a parent node that cannot be
+    #                          selected. This property is false by default.
+    #
+    # mutex_children:string - {'True','False'} Specify whether to limit
+    #                         the number of the category's child nodes
+    #                         that can be added to an audience segment to one.
+    #                         This property is false by default.
+    #
+    # notes:string - (Optional) Enter any notes to be associated with
+    #                this self-classification category.
+    #
+    # Example body hash = {name: 'a new category',
+    #                parent_id: '2342', description: 'an example category',
+    #                analytics_excluded: 'false', navigation_only: 'false',
+    #                mutex_children: 'false', notes: 'Just an API test' }
+    #
+    # Returns: hash of created category parameters including its category_id
+    def category_create(body)
+      request('POST', '/Services/WS/classificationCategories', {}, body)
+    end
+
+    # Public: Updates a given self-classification category
+    #
+    # category_id:integer - The unique ID assigned to the self-classification
+    #                       category to be updated
+    #
+    # name:string - Name of the self-classification category
+    #
+    # parent_id:integer - Unique ID of the parent node for the
+    #                     self-classification category.
+    #
+    # description:string - Description of uUser attribute
+    #                      represented by this category.
+    #
+    # analytics_excluded:string - {'True','False'} Specify whether the
+    #                   self-classification category is to be excluded
+    #                   from Audience Analytics reports. This property
+    #                   is false by default.
+    #
+    # navigation_only:string - {'True','False'} Specify whether the
+    #                          self-classification category functions
+    #                          exclusively as a parent node that cannot be
+    #                          selected. This property is false by default.
+    #
+    # mutex_children:string - {'True','False'} Specify whether to limit
+    #                         the number of the category's child nodes
+    #                         that can be added to an audience segment to one.
+    #                         This property is false by default.
+    #
+    # notes:string - (Optional) Enter any notes to be associated with
+    #                this self-classification category.
+    #
+    # Example body hash = {category_id: 1234, name: 'a chaged category',
+    #                     parent_id: '2342', description: 'an example category',
+    #                     analytics_exclued: 'false', navigation_only: 'false',
+    #                     mutex_children: 'false', notes: 'Just an API test' }
+    #
+    # Returns: hash of updated category parameters
+    def category_update(category_id, body)
+      request('PUT', "/Services/WS/classificationCategories/#{category_id}", {}, body)
+    end
+
+    ####
+    #### Classification Rules
+    #### API definition can be found here
+    #### https://kb.bluekai.com/display/PD/Self-Classification+Rule+API
+    ####
+
+    # Public: List the self-classification rules in your private
+    # taxonomy
+    #
+    # sort_by:string - Enter 'status', 'id', 'created_at', 'updated_at',
+    #                  or 'type' to sort the returned self-classification
+    #                  rules by the specified option.
+    #
+    # sorting_order:string  - Enter 'asc' or 'desc' to list the returned
+    #                         self-classification rules in ascending or descending
+    #                         order based on the specified sort option.
+    #
+    # ids:integer - Returns the self-classification rule matching the specified
+    #               rule ID, or returns all the self-classification rules matching
+    #               the specified list of rule IDs. Syntax for passing multiple rule IDs:
+    #               ruleId1&id=ruleId2 Example: 123&id=125
+    #
+    # type:enum  - Enter 'phint' or 'url' to return only the phint or
+    #              URL-based self-classification rules.
+    #
+    # site_ids:string  - Returns all the self-classification rules under the
+    #                    specified site ID or list of site IDs. Syntax for
+    #                    passing multiple site IDs: site_id_1&site_ids=site_id_2
+    #                    Example: 1234&site_ids=1235
+    #
+    # category_ids:string  - Returns all the self-classification rules used
+    #                        to map the specified catgeory ID or list of category IDs.
+    #                        Syntax for passing multiple category
+    #                        IDs: category_id_1&category_ids=category_id_2
+    #                        Example: 1234&category_ids=1235
+    #
+    # offset:integer - Specify the starting index from which to return the
+    #                  self-classification rules.
+    #
+    # size:integer - Specify the maximum number of rules to be included in
+    #                the response. This filter requires the offset filter
+    #                to be specified.
+    #
+    # created_date_range:string - Returns all the self-classification rules
+    #                             created within the specified list of dates.
+    #                             Syntax: YYYY-MM-DD&created_date_range=YYYY-MM-DD
+    #                             Example: 2014-01-01&created_date_range=2014-31-01
+    #
+    # updated_date_range:string  - Returns all the self-classification rules updated
+    #                              within the specified list of dates.
+    #                              Syntax: YYYY-MM-DD&updated_date_range=YYYY-MM-DD
+    #                              Example: 2014-01-01&updated_date_range=2014-31-01
+    #
+    # status:string - Enter 'Active' or 'Creating' to return the
+    #                 self-classification rules based on the specified status referrer
+    #                 boolean  Returns all URL-based self-classification rules that
+    #                 classify the site URL (False) or the referrer URL (True) in
+    #                 the collected URL.
+    #
+    # exact:boolean - Returns all URL-based self-classification rules that classify
+    #                 an exact URL (True) or a top-level URL (False) in the collected URL.
+    # Returns: hash of Bluekai rules
+    def rule_list(query)
+      request('GET', '/Services/WS/classificationRules', query)[:rules]
+    end
+
+    # Public: Reads a self-classification rule
+    #
+    # rule_id:integer - The unique ID assigned to the
+    # self-classification rule to be retrieved
+    #
+    # Returns: hash of Blukkai rule parameters
+    def rule_read(rule_id)
+      request('GET', "/Services/WS/classificationRules/#{rule_id}", {})
+    end
+
+    # Public: Creates a new self-classification rule
+    #
+    # name:string - Enter a string specifying the name of the self-classification rule.
+    #
+    # type:string - {'phint', 'url'} Specify the type of classification rule.
+    #
+    # phints:[{phint}] - If you are creating a phint-based rule,
+    #                    enter a list of your phint definitions.
+    #                    Each phint requires the following properties:
+    #                    key - The phint key operator - The criteria
+    #                    used for determining how the phint value
+    #                    is applied ('is' or 'contains')
+    #                    value - The full or partial phint value,
+    #                    depending on the specified operator.
+    #
+    # urls:[string(s)] - Provide a list of your URL definitions
+    #                    if you are creating for URL-based rules.
+    #
+    # referrer:string - {'True','False'} If you are creating a
+    #                   URL-based rule, specify whether the URL to
+    #                   be classified is the site URL (False) or
+    #                   the referrer URL (True).
+    #
+    # exact:string - {'True','False'} If you are creating a
+    #                URL-based rule, specify whether the URL collected
+    #                from your site must match the URL in your
+    #                rule (True) or match a top-level URL (False) so
+    #                that you can target users visiting the child pages
+    #                without specifying them.
+    #
+    # partner_id:integer - Enter the unique ID assigned to your BlueKai DMP seat.
+    #
+    # site_ids (optional):[interger(s)] - Enter a list of containers/site IDs to which
+    #                                     the self-classification rule applies. If
+    #                                     you do not include this parameter, the
+    #                                     rule is applicable to ALL the
+    #                                     container/site IDs in your seat.
+    #
+    # category_ids:[integer(s)] - a list of category IDs to which
+    #                             the self-classification rule applies.
+    #
+    # JSON example for Phint-based self-classification rule
+    # {
+    # "name": "Phint Example",
+    # "type": "phint",
+    # "phints": [
+    # {
+    # "key": "x",
+    # "value": "123",
+    # "operator": "is"
+    # }
+    # ],
+    # "partner_id": 123,
+    # "site_ids": [1234],
+    # "category_ids": [12345]
+    # }
+    #
+    # JSON example for URL-based self-classiifcation rule
+    # {
+    # "name": "URL Example",
+    # "type": "url",
+    # "urls": ["http://shop.yoursite.com"],
+    # "referrer": false,
+    # "exact": false,
+    # "partner_id": 123,
+    # "site_ids": [1234],
+    # "category_ids": [123456]
+    # }
+    # Returns: hash of created self-classification rule
+    def rule_create(body)
+      body = { partner_id: @partner_id }.merge(body)
+      request('POST', '/Services/WS/classificationRules', {}, body)
+    end
+
+    # Public: Update a self-classification rule
+    #
+    # rule_id:integer (MANDATORY) - id of classification rule to be updated
+    #
+    # for other parameters refer to documentation of rule_create(body)
+    #
+    # Returns: hash of updated self-classification rule
+    def rule_update(rule_id, body)
+      body = { partner_id: @partner_id }.merge(body)
+      request('PUT', "/Services/WS/classificationRules/#{rule_id}", {}, body)
+    end
+
+    private
+
+    def request(method, path, query, body = nil)
+      method.upcase!
+      signature = sign(method, path, query_values(query), body_sorted(body))
+
+      url = "https://#{domain}#{path}?#{query_url_formatted(query)}\
+bkuid=#{api_user_key}&bksig=#{signature}"
+
+      response =  case method
+                  when 'GET'
+                    HTTParty.get(url)
+                  when 'POST'
+                    HTTParty.post(url, body: body_sorted(body), headers: json_headers)
+                  when 'PUT'
+                    HTTParty.put(url, body: body_sorted(body), headers: json_headers)
+                  else
+                    fail ArgumentError, "request method '#{method}' not supported"
+                  end.response
+      fail "HTTP Request Error: #{response.body}" if response.code != '200'
+      return response.code if response.body == '' || response.body.nil?
+      JSON.parse(response.body, symbolize_names: true)
+    end
+
+    def body_sorted(body)
+      # sort hash according to keys for correct signature computation
+      return body.sort_by { |key, _value| key.to_s }.to_h.to_json if body
+    end
+
+    def json_headers
+      {
+        'Accept' => 'application/json',
+        'Content-type' => 'application/json'
+      }
+    end
+
+    def query_values(query)
+      return nil unless query
+      query.values.join
+    end
+
+    def query_url_formatted(query)
+      return nil unless query
+      query.map { |k, v| "#{k}=#{v}" }.join('&') + '&'
+    end
+
+    # HMAC-SHA256(Secret key, HTTP_METHOD + URI_PATH + QUERY_ARG_VALUES + POST_DATA)
+    def sign(method, path, query, body)
+      string_to_sign = method + path + query.to_s + body.to_s
+      digest = OpenSSL::Digest.new('sha256')
+      hmac = OpenSSL::HMAC.digest(digest, @api_private_key, string_to_sign)
+      CGI.escape(Base64.strict_encode64(hmac))
+    end
+  end
+end