Support for Audience Intelligence (#171)

* bump up version to 3; added AI enums

* added AI endpoints and example

* fixed code style issues

* more code style fixes

* fixes lint issues; refactor rubocop to ignore false positives

.rubocop.yml

@@ -32,6 +32,9 @@ Metrics/ParameterLists:
 Performance/Casecmp:
   Enabled: false
 
+Style/MixinGrouping:
+  Enabled: false
+
 Style/MultilineMethodCallBraceLayout:
   Enabled: false
 

examples/audience_intelligence.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+require 'twitter-ads'
+
+CONSUMER_KEY        = 'your consumer key'.freeze
+CONSUMER_SECRET     = 'your consumer secret'.freeze
+ACCESS_TOKEN        = 'user access token'.freeze
+ACCESS_TOKEN_SECRET = 'user access token secret'.freeze
+ADS_ACCOUNT         = 'ads account id'.freeze
+
+# initialize the twitter ads api client
+client = TwitterAds::Client.new(
+  CONSUMER_KEY,
+  CONSUMER_SECRET,
+  ACCESS_TOKEN,
+  ACCESS_TOKEN_SECRET
+)
+
+# load up the account instance, campaign and line item
+account = client.accounts(ADS_ACCOUNT)
+
+audience_conversations = TwitterAds::AudienceIntelligence.new(account)
+audience_conversations.conversation_type = TwitterAds::Enum::ConversationType::HASHTAG
+audience_conversations.audience_definition = TwitterAds::Enum::AudienceDefinition \
+  ::TARGETING_CRITERIA
+targeting_inputs =
+  [{
+    targeting_type: 'GENDER',
+    targeting_value: '2'
+  }, {
+    targeting_type: 'AGEBUCKET',
+    targeting_value: 'AGE_OVER_50'
+  }]
+
+audience_conversations.targeting_inputs = targeting_inputs
+# returns a cursor instance
+response = audience_conversations.conversations
+response.each do |ai|
+  puts ai.localized[:targeting_type]
+  puts ai.localized[:targeting_value]
+  puts '\n'
+end
+
+audience_demographics = TwitterAds::AudienceIntelligence.new(account)
+audience_demographics.audience_definition = TwitterAds::Enum::AudienceDefinition::KEYWORD_AUDIENCE
+audience_demographics.targeting_inputs =
+  [{
+    targeting_type: 'BROAD_MATCH_KEYWORD',
+    targeting_value: 'womensmarch2018',
+    start_time: '2017-12-31'
+  }]
+# returns raw response body
+demographics = audience_demographics.demographics
+demographics.each do |demo|
+  puts demo
+  puts "\n"
+end

lib/twitter-ads/audiences/audience_intelligence.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class AudienceIntelligence
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource::InstanceMethods
+
+    attr_reader :account
+
+    # writable
+    property :conversation_type
+    property :targeting_inputs
+    property :audience_definition
+
+    # demographics-only
+    property :start_time, type: :time
+    property :end_time, type: :time
+
+    # read
+    property :operator_type, read_only: true
+    property :targeting_type, read_only: true
+    property :targeting_value, read_only: true
+    property :localized, read_only: true
+
+    RESOURCE_CONVERSATIONS  = "/#{TwitterAds::API_VERSION}/" \
+                              'accounts/%{account_id}/audience_intelligence/' \
+                              'conversations'.freeze # @api private
+    RESOURCE_DEMOGRAPHICS   = "/#{TwitterAds::API_VERSION}/" \
+                              'accounts/%{account_id}/audience_intelligence/' \
+                              'demographics'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+    def conversations
+      headers = { 'Content-Type' => 'application/json' }
+      params = {
+        conversation_type: conversation_type,
+        audience_definition: audience_definition,
+        targeting_inputs: targeting_inputs
+      }
+      resource = RESOURCE_CONVERSATIONS % { account_id: account.id }
+      request = Request.new(account.client, :post, resource, body: params.to_json, headers: headers)
+      Cursor.new(self.class, request, init_with: [account])
+    end
+
+    def demographics
+      headers = { 'Content-Type' => 'application/json' }
+      params = {
+        audience_definition: audience_definition,
+        targeting_inputs: targeting_inputs
+      }
+      resource = RESOURCE_DEMOGRAPHICS % { account_id: account.id }
+      response = Request.new(
+        account.client,
+        :post,
+        resource,
+        body: params.to_json,
+        headers: headers).perform
+      response.body[:data]
+      # cannot use cursor here given that the response "keys" are dynmaic based on input values
+    end
+  end
+end

lib/twitter-ads/enum.rb

@@ -198,5 +198,15 @@ module TrackingPartner
       DOUBLE_CLICK = 'DOUBLE_CLICK'.freeze
     end
 
+    module ConversationType
+      EVENT = 'EVENT'.freeze
+      HANDLE = 'HANDLE'.freeze
+      HASHTAG = 'HASHTAG'.freeze
+    end
+
+    module AudienceDefinition
+      TARGETING_CRITERIA = 'TARGETING_CRITERIA'.freeze
+      KEYWORD_AUDIENCE = 'KEYWORD_AUDIENCE'.freeze
+    end
   end
 end

lib/twitter-ads/version.rb

@@ -2,5 +2,5 @@
 # Copyright (C) 2015 Twitter, Inc.
 
 module TwitterAds
-  VERSION = '2.0.0'.freeze
+  VERSION = '3.0.0'.freeze
 end