twitter-ads 0.3.4 → 1.0.0

data/lib/twitter-ads/http/request.rb

@@ -23,7 +23,7 @@ module TwitterAds
     # Creates a new Request object instance.
     #
     # @example
-    #   request = Request.new(client, :get, '/0/accounts')
+    #   request = Request.new(client, :get, '/1/accounts')
     #
     # @param client [Client] The Client object instance.
     # @param method [Symbol] The HTTP method to be used.
@@ -47,7 +47,7 @@ module TwitterAds
     # Executes the current Request object.
     #
     # @example
-    #   request = Request.new(client, :get, '/0/accounts')
+    #   request = Request.new(client, :get, '/1/accounts')
     #   request.perform
     #
     # @since  0.1.0

data/lib/twitter-ads/resources/analytics.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 # Copyright (C) 2015 Twitter, Inc.
 
+require 'zlib'
+require 'open-uri'
+
 module TwitterAds
   module Analytics
 
-    CLASS_ID_MAP = {
-      'TwitterAds::LineItem'                => :line_item_ids,
-      'TwitterAds::OrganicTweet'            => :tweet_ids,
-      'TwitterAds::Tweet'                   => :tweet_ids,
-      'TwitterAds::Creative::PromotedTweet' => :promoted_tweet_ids
-    }.freeze # @api private
+    ANALYTICS_MAP = {
+      'TwitterAds::LineItem' => 'LINE_ITEM'.freeze,
+      'TwitterAds::OrganicTweet' => 'ORGANIC_TWEET'.freeze,
+      'TwitterAds::Creative::PromotedTweet' => 'PROMOTED_TWEET'.freeze
+    }.freeze
 
     def self.included(klass)
       klass.send :include, InstanceMethods
@@ -21,22 +23,21 @@ module TwitterAds
       # Pulls a list of metrics for the current object instance.
       #
       # @example
-      #   metrics = [:promoted_tweet_timeline_clicks, :promoted_tweet_search_clicks]
+      #   metric_groups = [:promoted_tweet_timeline_clicks, :promoted_tweet_search_clicks]
       #   object.stats(metrics)
       #
-      # @param metrics [Array] A collection of valid metrics to be fetched.
+      # @param metric_groups [Array] A collection of metric groups to fetch.
       # @param opts [Hash] An optional Hash of extended options.
       # @option opts [Time] :start_time The starting time to use (default: 7 days ago).
       # @option opts [Time] :end_time The end time to use (default: now).
       # @option opts [Symbol] :granularity The granularity to use (default: :hour).
-      # @option opts [Symbol] :segmentation_type The segmentation type to use (default: none).
       #
       # @return [Array] The collection of stats requested.
       #
       # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
-      # @since 0.1.0
-      def stats(metrics, opts = {})
-        self.class.stats(account, [id], metrics, opts)
+      # @since 1.0.0
+      def stats(metric_groups, opts = {})
+        self.class.stats(account, [id], metric_groups, opts)
       end
 
     end
@@ -47,43 +48,147 @@ module TwitterAds
       #
       # @example
       #   ids = ['7o4em', 'oc9ce', '1c5lji']
-      #   metrics = [:promoted_tweet_timeline_clicks, :promoted_tweet_search_clicks]
-      #   object.stats(account, ids, metrics)
+      #   metric_groups = [MetricGroups.MOBILE_CONVERSION, MetricGroups.ENGAGEMENT]
+      #   object.stats(account, ids, metric_groups)
       #
       # @param account [Account] The Account object instance.
       # @param ids [Array] A collection of object IDs being targeted.
-      # @param metrics [Array] A collection of valid metrics to be fetched.
+      # @param metric_groups [Array] A collection of metric_groups to be fetched.
       # @param opts [Hash] An optional Hash of extended options.
       # @option opts [Time] :start_time The starting time to use (default: 7 days ago).
       # @option opts [Time] :end_time The end time to use (default: now).
       # @option opts [Symbol] :granularity The granularity to use (default: :hour).
-      # @option opts [Symbol] :segmentation_type The segmentation type to use (default: none).
+      # @option opts [Symbol] :placement The placement of entity (default: ALL_ON_TWITTER).
       #
       # @return [Array] The collection of stats requested.
       #
       # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
-      # @since 0.1.0
-      def stats(account, ids, metrics, opts = {})
+      # @since 1.0.0
+
+      def stats(account, ids, metric_groups, opts = {})
         # set default metric values
-        end_time          = opts.fetch(:end_time, Time.now)
+        end_time          = opts.fetch(:end_time, (Time.now - Time.now.sec - (60 * Time.now.min)))
         start_time        = opts.fetch(:start_time, end_time - 604_800) # 7 days ago
         granularity       = opts.fetch(:granularity, :hour)
-        segmentation_type = opts.fetch(:segmentation_type, nil)
+        placement         = opts.fetch(:placement, Placement::ALL_ON_TWITTER)
 
         params = {
-          metrics: metrics.join(','),
+          metric_groups: metric_groups.join(','),
           start_time: TwitterAds::Utils.to_time(start_time, granularity),
           end_time: TwitterAds::Utils.to_time(end_time, granularity),
-          granularity: granularity.to_s.upcase
+          granularity: granularity.to_s.upcase,
+          entity: ANALYTICS_MAP[name],
+          placement: placement
         }
-        params[:segmentation_type] = segmentation_type.to_s.upcase if segmentation_type
-        params[TwitterAds::Analytics::CLASS_ID_MAP[name]] = ids.join(',')
+
+        params['entity_ids'] = ids.join(',')
 
         resource = self::RESOURCE_STATS % { account_id: account.id }
         response = Request.new(account.client, :get, resource, params: params).perform
         response.body[:data]
       end
 
+      # Create an asynchronous analytics job for a given ads account.
+      # A job_id is returned, which you can use to poll the
+      # GET /1/stats/jobs/accounts/:account_id endpoint, checking until the job is successful.
+      #
+      # @example
+      #   ids = ['7o4em', 'oc9ce', '1c5lji']
+      #   metric_groups = [MetricGroups.MOBILE_CONVERSION, MetricGroups.ENGAGEMENT]
+      #   object.create_async_job(account, ids, metric_groups)
+      #
+      # @param account [Account] The Account object instance.
+      # @param ids [Array] A collection of object IDs being targeted.
+      # @param metric_groups [Array] A collection of metric_groups to be fetched.
+      # @param opts [Hash] An optional Hash of extended options.
+      # @option opts [Time] :start_time The starting time to use (default: 7 days ago).
+      # @option opts [Time] :end_time The end time to use (default: now).
+      # @option opts [Symbol] :granularity The granularity to use (default: :hour).
+      # @option opts [Symbol] :placement The placement of entity (default: ALL_ON_TWITTER).
+      # @option opts [Symbol] :segmentation_type The segmentation type to use (default: none).
+      #
+      # @return The response of creating job
+      #
+      # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
+      # @sync 1.0.0
+
+      def create_async_job(account, ids, metric_groups, opts = {})
+        # set default metric values
+        end_time          = opts.fetch(:end_time, (Time.now - Time.now.sec - (60 * Time.now.min)))
+        start_time        = opts.fetch(:start_time, end_time - 604_800) # 7 days ago
+        granularity       = opts.fetch(:granularity, :hour)
+        placement         = opts.fetch(:placement, Placement::ALL_ON_TWITTER)
+        segmentation_type = opts.fetch(:segmentation_type, nil)
+
+        params = {
+          metric_groups: metric_groups.join(','),
+          start_time: TwitterAds::Utils.to_time(start_time, granularity),
+          end_time: TwitterAds::Utils.to_time(end_time, granularity),
+          granularity: granularity.to_s.upcase,
+          entity: ANALYTICS_MAP[name],
+          placement: placement
+        }
+
+        params[:segmentation_type] = segmentation_type.to_s.upcase if segmentation_type
+        params['entity_ids'] = ids.join(',')
+
+        resource = self::RESOURCE_ASYNC_STATS % { account_id: account.id }
+        puts 'my resource is ' + resource
+        response = Request.new(account.client, :post, resource, params: params).perform
+        response.body[:data]
+      end
+
+      # Check async job status.
+      # GET /1/stats/jobs/accounts/:account_id
+      #
+      # @example
+      #   TwitterAds::LineItem.check_async_job_status(account, job_id: '1357343438724431305')
+      #
+      # @param account [Account] The Account object instance.
+      # @option opts [String] :job_id The starting time to use (default: 7 days ago).
+      #
+      # @return A cursor of job statuses
+
+      def check_async_job_status(account, opts = {})
+        # set default values
+        job_id = opts.fetch(:job_id, nil)
+        params = {}
+        params[:job_id] = job_id if job_id
+
+        resource = self::RESOURCE_ASYNC_STATS % { account_id: account.id }
+        request = Request.new(account.client, :get, resource, params: params)
+        Cursor.new(nil, request, init_with: [account])
+      end
+
+      # Fetch async job data for a completed job.
+      # Raises HTTP 404 exception, otherwise retries up to 5 times with exponential backoff.
+      #
+      # @example
+      #   response_data = TwitterAds::LineItem.fetch_async_job_data(account, file_url)
+      #
+      # @param data_url [String] The URL from the successful completion of an async job.
+      #
+      # @return A cursor of job statuses
+
+      def fetch_async_job_data(data_url)
+        tries = 0
+        begin
+          tries += 1
+          raw_file = open(data_url)
+          unzipped_file = Zlib::GzipReader.new(raw_file)
+          response_data = unzipped_file.read
+          response = JSON.parse(response_data)
+          response['data']
+        rescue OpenURI::HTTPError => e
+          unless e.io.status[0] == '404'
+            if tries < 5
+              sleep(2**tries)
+              retry
+            end
+          end
+        end
+      end
+
     end
 
   end

data/lib/twitter-ads/resources/dsl.rb

@@ -56,7 +56,7 @@ module TwitterAds
           elsif type == :bool
             params[name] = TwitterAds::Utils.to_bool(value)
           elsif value.is_a?(Array)
-            next if value.size < 1
+            next if value.empty?
             params[name] = value.join(',')
           else
             params[name] = value

data/lib/twitter-ads/targeting/reach_estimate.rb

@@ -13,20 +13,20 @@ module TwitterAds
       #     account,
       #     'PROMOTED_TWEETS',
       #     'WEBSITE_CLICKS',
-      #     2153688540,
+      #     5500000,
+      #     30000000,
       #     similar_to_followers_of_user: 2153688540,
       #     gender: 2
       #   )
       #
       # @param client [Client] The Client object instance.
-      # @param account [Account] The Ads Account instance for this request.
       # @param product_type [String] The product type being targeted.
       # @param objective [String] The objective being targeted.
-      # @param user_id [Long] The ID of the user whose content will be promoted.
+      # @param campaign_daily_budget_amount_local_micro [Long] Daily budget in micros.
       # @param opts [Hash] A Hash of extended options.
       #
-      # @option opts [String] :bid_type The bidding mechanism.
       # @option opts [Long] :bid_amount_local_micro Bid amount in local currency micros.
+      # @option opts [String] :bid_type The bidding mechanism.
       # @option opts [String] :currency ISO-4217 Currency code for bid amount.
       # @option opts [String] :followers_of_users Comma-separated user IDs.
       # @option opts [String] :similar_to_followers_of_users Comma-separated user IDs.
@@ -44,14 +44,20 @@ module TwitterAds
       # @option opts [String] :campaign engagement Campaign ID for Tweet Engager Retargeting.
       # @option opts [String] :user_engagement Promoted User ID for Tweet Engager Retargeting.
       # @option opts [String] :engagement_type engagement type for Tweet Engager Retargeting.
+      # @option opts [String] :network_operators Network operators to target
+      # @option opts [String] :app_store_categories App store categories to target.
+      # @option opts [String] :app_store_categories_expanded App store categories with lookalikes.
       #
       # @return [Hash] A hash containing count and infinite_bid_count.
       #
-      # @since 0.2.0
-      # @see https://dev.twitter.com/ads/reference/get/accounts/%3Aaccount_id/reach_estimate
-      def fetch(account, product_type, objective, user_id, opts = {})
-        resource = "/0/accounts/#{account.id}/reach_estimate"
-        params = { product_type: product_type, objective: objective, user_id: user_id }.merge!(opts)
+      # @since 1.0.0
+      # @see https://dev.twitter.com/ads/reference/1/get/accounts/%3Aaccount_id/reach_estimate
+      def fetch(account, product_type, objective, campaign_daily_budget,
+                opts = {})
+        resource = "/1/accounts/#{account.id}/reach_estimate"
+        params = { product_type: product_type, objective: objective,
+                   campaign_daily_budget_amount_local_micro: campaign_daily_budget
+                 }.merge!(opts)
 
         # The response value count is "bid sensitive", we default to bid_type=AUTO here to preserve
         # expected behavior despite an API change that occurred in December 2015.
@@ -59,7 +65,8 @@ module TwitterAds
           params = { bid_type: 'AUTO' }.merge!(params)
         end
 
-        response = TwitterAds::Request.new(account.client, :get, resource, params: params).perform
+        response = TwitterAds::Request.new(account.client, :get,
+                                           resource, params: params).perform
         response.body[:data]
       end
 

data/lib/twitter-ads/targeting_criteria/app_store_category.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class AppStoreCategory
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    property :name, read_only: true
+    property :os_type, read_only: true
+    property :targeting_type, read_only: true
+    property :targeting_value, read_only: true
+
+    RESOURCE_COLLECTION = '/1/targeting_criteria/app_store_categories'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+  end
+end

data/lib/twitter-ads/targeting_criteria/behavior.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class Behavior
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    property :id, read_only: true
+    property :name, read_only: true
+    property :targeting_type, read_only: true
+    property :targeting_value, read_only: true
+    property :audience_code, read_only: true
+    property :country_code, read_only: true
+    property :partner_source, read_only: true
+    property :targetable_type, read_only: true
+
+    RESOURCE_COLLECTION = '/1/targeting_criteria/behaviors'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+  end
+end

data/lib/twitter-ads/targeting_criteria/behavior_taxonomy.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class BehaviorTaxonomy
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    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
+
+    RESOURCE_COLLECTION = '/1/targeting_criteria/behavior_taxonomies'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+  end
+end

data/lib/twitter-ads/targeting_criteria/device.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class Device
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    property :id, read_only: true
+    property :name, read_only: true
+    property :targeting_type, read_only: true
+    property :targeting_value, read_only: true
+    property :platform, read_only: true
+    property :manufacturer, read_only: true
+
+    RESOURCE_COLLECTION = '/1/targeting_criteria/devices'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+  end
+end

data/lib/twitter-ads/targeting_criteria/event.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class Event
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    property :id, read_only: true
+    property :name, read_only: true
+    property :reach, read_only: true
+    property :start_time, read_only: true
+    property :end_time, read_only: true
+    property :top_users, read_only: true
+    property :top_tweets, read_only: true
+    property :top_hashtags, read_only: true
+    property :country_code, read_only: true
+    property :is_global, read_only: true
+    property :category, read_only: true
+    property :gender_breakdown_percentage, read_only: true
+    property :device_breakdown_percentage, read_only: true
+    property :country_breakdown_percentage, read_only: true
+
+    RESOURCE_COLLECTION = '/1/targeting_criteria/events'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+  end
+end

data/lib/twitter-ads/targeting_criteria/interest.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class Interest
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    property :name, read_only: true
+    property :targeting_type, read_only: true
+    property :targeting_value, read_only: true
+    property :localized_name, read_only: true
+
+    RESOURCE_COLLECTION = '/1/targeting_criteria/interests'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+  end
+end