Ads API v7 (#224)

* bump version to 7

* changed serving_status to entity_status for media creatives

* added granular tap placements

* removed deprecated behavior targeting

* added advertiser business categories endpoint

* added missing content categories endpoint

* added audience summary and tests

* removed scoped timeline endpoint

examples/audience_summary.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# Copyright (C) 2019 Twitter, Inc.
+require 'twitter-ads'
+
+CONSUMER_KEY        = 'your consumer key'
+CONSUMER_SECRET     = 'your consumer secret'
+ACCESS_TOKEN        = 'user access token'
+ACCESS_TOKEN_SECRET = 'user access token secret'
+ADS_ACCOUNT         = 'ads account id'
+
+# initialize the twitter ads api client
+client = TwitterAds::Client.new(
+  CONSUMER_KEY,
+  CONSUMER_SECRET,
+  ACCESS_TOKEN,
+  ACCESS_TOKEN_SECRET
+)
+
+# load up the account instance
+account = client.accounts(ADS_ACCOUNT)
+
+# targeting criteria params
+params = {
+  targeting_criteria: [
+    {
+      targeting_type: 'LOCATION',
+      targeting_value: '96683cc9126741d1'
+    },
+    {
+      targeting_type: 'BROAD_KEYWORD',
+      targeting_value: 'cats'
+    },
+    {
+      targeting_type: 'SIMILAR_TO_FOLLOWERS_OF_USER',
+      targeting_value: '14230524'
+    },
+    {
+      targeting_type: 'SIMILAR_TO_FOLLOWERS_OF_USER',
+      targeting_value: '90420314'
+    }
+  ]
+}
+
+audience_summary = TwitterAds::AudienceSummary.fetch(account, params)
+puts audience_summary

lib/twitter-ads.rb

@@ -40,6 +40,8 @@
 require 'twitter-ads/campaign/tweet'
 require 'twitter-ads/campaign/organic_tweet'
 require 'twitter-ads/campaign/iab_category'
+require 'twitter-ads/campaign/advertiser_business_categories'
+require 'twitter-ads/campaign/content_categories'
 
 require 'twitter-ads/targeting_criteria/tv_market'
 require 'twitter-ads/targeting_criteria/tv_show'
@@ -52,8 +54,6 @@
 require 'twitter-ads/targeting_criteria/location'
 require 'twitter-ads/targeting_criteria/interest'
 require 'twitter-ads/targeting_criteria/language'
-require 'twitter-ads/targeting_criteria/behavior'
-require 'twitter-ads/targeting_criteria/behavior_taxonomy'
 require 'twitter-ads/targeting_criteria/app_store_category'
 
 require 'twitter-ads/creative/account_media'
@@ -74,7 +74,7 @@
 require 'twitter-ads/creative/tweet_previews'
 require 'twitter-ads/creative/tweets'
 
-require 'twitter-ads/targeting/reach_estimate'
+require 'twitter-ads/targeting/audience_summary'
 
 require 'twitter-ads/measurement/web_event_tag'
 require 'twitter-ads/measurement/app_event_tag'

lib/twitter-ads/account.rb

@@ -23,7 +23,6 @@ class Account
                                 'accounts/%{id}' # @api private
     FEATURES                  = "/#{TwitterAds::API_VERSION}/" \
                                 'accounts/%{id}/features' # @api private
-    SCOPED_TIMELINE           = '/5/accounts/%{id}/scoped_timeline' # @api private
     AUTHENTICATED_USER_ACCESS = "/#{TwitterAds::API_VERSION}/" \
                                 'accounts/%{id}/authenticated_user_access' # @api private
 
@@ -247,24 +246,6 @@ def tailored_audiences(id = nil, opts = {})
       load_resource(TailoredAudience, id, opts)
     end
 
-    # Returns the most recent promotable Tweets created by one or more specified Twitter users.
-    #
-    # @param ids [Array] An Array of Twitter user IDs.
-    # @param opts [Hash] A Hash of extended options.
-    #
-    # @return [Array] An Array of Tweet objects.
-    #
-    # @since 0.2.3
-    def scoped_timeline(id, opts = {})
-      TwitterAds::Utils.deprecated(
-        'Scoped Timeline')
-      params   = { user_id: id }.merge!(opts)
-      resource = SCOPED_TIMELINE % { id: @id }
-      request  = Request.new(client, :get, resource, params: params)
-      response = request.perform
-      response.body[:data]
-    end
-
     def authenticated_user_access
       params = {}
       resource = AUTHENTICATED_USER_ACCESS % { id: @id }

lib/twitter-ads/targeting_criteria/behavior_taxonomy.rb → lib/twitter-ads/campaign/advertiser_business_categories.rb

@@ -2,19 +2,19 @@
 # Copyright (C) 2019 Twitter, Inc.
 
 module TwitterAds
-  class BehaviorTaxonomy
+  class AdvertiserBusinessCategories
 
     include TwitterAds::DSL
     include TwitterAds::Resource
 
+    attr_reader :account
+
     property :id, read_only: true
     property :name, read_only: true
-    property :parent_id, read_only: true
-    property :created_at, read_only: true
-    property :updated_at, read_only: true
+    property :iab_categories, read_only: true
 
-    RESOURCE_COLLECTION = "/#{TwitterAds::API_VERSION}/" \
-                          'targeting_criteria/behavior_taxonomies' # @api private
+    # @api private
+    RESOURCE_COLLECTION = "/#{TwitterAds::API_VERSION}/advertiser_business_categories"
 
     def initialize(account)
       @account = account

lib/twitter-ads/campaign/content_categories.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Copyright (C) 2019 Twitter, Inc.
+
+module TwitterAds
+  class ContentCategories
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :name, read_only: true
+    property :iab_categories, read_only: true
+
+    RESOURCE_COLLECTION = "/#{TwitterAds::API_VERSION}/content_categories" # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+  end
+end

lib/twitter-ads/client.rb

@@ -3,7 +3,7 @@
 
 module TwitterAds
 
-  API_VERSION = '6'
+  API_VERSION = '7'
 
   # The Ads API Client class which functions as a
   # container for basic API consumer information.

lib/twitter-ads/creative/media_creative.rb

@@ -16,7 +16,7 @@ class MediaCreative < Analytics
       property :created_at, type: :time, read_only: true
       property :deleted, type: :bool, read_only: true
       property :id, read_only: true
-      property :serving_status, read_only: true
+      property :entity_status, read_only: true
       property :updated_at, type: :time, read_only: true
 
       property :account_media_id

lib/twitter-ads/enum.rb

@@ -24,10 +24,15 @@ module Product
     end
 
     module Placement
-      ALL_ON_TWITTER    = 'ALL_ON_TWITTER'
-      TWITTER_SEARCH    = 'TWITTER_SEARCH'
-      TWITTER_TIMELINE  = 'TWITTER_TIMELINE'
-      PUBLISHER_NETWORK = 'PUBLISHER_NETWORK'
+      ALL_ON_TWITTER     = 'ALL_ON_TWITTER'
+      TWITTER_SEARCH     = 'TWITTER_SEARCH'
+      TWITTER_TIMELINE   = 'TWITTER_TIMELINE'
+      PUBLISHER_NETWORK  = 'PUBLISHER_NETWORK'
+      TAP_FULL           = 'TAP_FULL'
+      TAP_FULL_LANDSCAPE = 'TAP_FULL_LANDSCAPE'
+      TAP_BANNER         = 'TAP_BANNER'
+      TAP_NATIVE         = 'TAP_NATIVE'
+      TAP_MRECT          = 'TAP_MRECT'
     end
 
     module Placement

lib/twitter-ads/targeting/audience_summary.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# Copyright (C) 2019 Twitter, Inc.
+
+module TwitterAds
+  module AudienceSummary
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    RESOURCE = "/#{TwitterAds::API_VERSION}/" \
+                           'accounts/%{account_id}/audience_summary'
+
+    property :audience_size, read_only: true
+
+    class << self
+
+      # Get an audience summary for the specified targeting criteria.
+      #
+      # @example
+      #   TwitterAds::AudienceSummary.fetch(
+      #     account,
+      #     params: {targeting_criteria:[{targeting_type:'LOCATION',
+      #             targeting_value:'96683cc9126741d1'}]}
+      #   )
+      #
+      # @param params [Hash] A hash of input targeting criteria values
+      #
+      # @return [Hash] A hash containing the min and max audience size.
+      #
+      # @since 7.0.0
+      # @see https://developer.twitter.com/en/docs/ads/campaign-management/api-reference/audience-summary
+      def fetch(account, params)
+        resource = RESOURCE % { account_id: account.id }
+        headers = { 'Content-Type' => 'application/json' }
+
+        response = TwitterAds::Request.new(account.client,
+                                           :post,
+                                           resource,
+                                           headers: headers,
+                                           body: params.to_json).perform
+        response.body[:data]
+      end
+
+    end
+
+  end
+end

lib/twitter-ads/version.rb

@@ -2,5 +2,5 @@
 # Copyright (C) 2019 Twitter, Inc.
 
 module TwitterAds
-  VERSION = '6.0.1'
+  VERSION = '7.0.0'
 end

spec/fixtures/audience_summary.json

@@ -0,0 +1,14 @@
+{
+  "request": {
+    "params": {
+      "targeting_criteria": null,
+      "account_id": "2iqph"
+    }
+  },
+  "data": {
+    "audience_size": {
+      "min": 41133600,
+      "max": 50274400
+    }
+  }
+}