twitter-ads 5.2.0 → 6.0.0

data/lib/twitter-ads/creative/video_app_download_card.rb

@@ -18,15 +18,13 @@ module TwitterAds
       property :deleted, type: :bool, read_only: true
       property :id, read_only: true
       property :updated_at, type: :time, read_only: true
-      property :video_content_id, read_only: true
-      property :video_hls_url, read_only: true
       property :video_owner_id, read_only: true
-      property :video_poster_url, read_only: true
-      property :video_url, read_only: true
+      property :poster_media_url, read_only: true
+      property :media_url, read_only: true
 
       property :country_code
       property :app_cta
-      property :image_media_id
+      property :poster_media_key
       property :ipad_app_id
       property :ipad_deep_link
       property :iphone_app_id
@@ -34,7 +32,7 @@ module TwitterAds
       property :googleplay_app_id
       property :googleplay_deep_link
       property :name
-      property :video_id
+      property :media_key
 
       RESOURCE_COLLECTION = "/#{TwitterAds::API_VERSION}/" \
                             'accounts/%{account_id}/cards/video_app_download' # @api private

data/lib/twitter-ads/creative/video_conversation_card.rb

@@ -18,14 +18,14 @@ module TwitterAds
       property :deleted, type: :bool, read_only: true
       property :id, read_only: true
       property :updated_at, type: :time, read_only: true
-      property :video_url, read_only: true
-      property :video_poster_url, read_only: true
+      property :media_url, read_only: true
+      property :poster_media_url, read_only: true
 
-      property :cover_image_id
-      property :cover_video_id
+      property :unlocked_image_media_key
+      property :unlocked_video_media_key
       property :fourth_cta
       property :fourth_cta_tweet
-      property :image_media_id
+      property :poster_media_key
       property :first_cta
       property :first_cta_tweet
       property :name
@@ -36,7 +36,7 @@ module TwitterAds
       property :third_cta
       property :third_cta_tweet
       property :title
-      property :video_id
+      property :media_key
 
       RESOURCE_COLLECTION = "/#{TwitterAds::API_VERSION}/" \
                             'accounts/%{account_id}/cards/video_conversation' # @api private

data/lib/twitter-ads/creative/video_website_card.rb

@@ -19,21 +19,19 @@ module TwitterAds
       property :deleted, type: :bool, read_only: true
       property :id, read_only: true
       property :updated_at, type: :time, read_only: true
-      property :video_content_id, read_only: true
       property :video_height, read_only: true
-      property :video_hls_url, read_only: true
       property :video_owner_id, read_only: true
       property :video_poster_height, read_only: true
-      property :video_poster_url, read_only: true
+      property :poster_media_url, read_only: true
       property :video_poster_width, read_only: true
-      property :video_url, read_only: true
+      property :media_url, read_only: true
       property :video_width, read_only: true
       property :website_display_url, read_only: true
       property :website_dest_url, read_only: true
 
       property :name
       property :title
-      property :video_id
+      property :media_key
       property :website_url
 
       RESOURCE_COLLECTION = "/#{TwitterAds::API_VERSION}/accounts/%{account_id}/cards/video_website"

data/lib/twitter-ads/creative/website_card.rb

@@ -17,14 +17,14 @@ module TwitterAds
       property :created_at, type: :time, read_only: true
       property :deleted, type: :bool, read_only: true
       property :id, read_only: true
-      property :image, read_only: true
+      property :media_url, read_only: true
       property :image_display_height, read_only: true
       property :image_display_width, read_only: true
       property :updated_at, type: :time, read_only: true
       property :website_dest_url, read_only: true
       property :website_display_url, read_only: true
 
-      property :image_media_id
+      property :media_key
       property :name
       property :website_title
       property :website_url

data/lib/twitter-ads/cursor.rb

@@ -112,6 +112,12 @@ module TwitterAds
     def from_response(response)
       @next_cursor = response.body[:next_cursor]
       @total_count = response.body[:total_count].to_i if response.body.key?(:total_count)
+
+      TwitterAds::Utils.extract_response_headers(response.headers).each { |key, value|
+        singleton_class.class_eval { attr_accessor key }
+        instance_variable_set("@#{key}", value)
+      }
+
       response.body.fetch(:data, []).each do |object|
         @collection << if @klass&.method_defined?(:from_response)
                          @klass.new(

data/lib/twitter-ads/enum.rb

@@ -106,6 +106,7 @@ module TwitterAds
       FUNDING_INSTRUMENT = 'FUNDING_INSTRUMENT'
       CAMPAIGN           = 'CAMPAIGN'
       LINE_ITEM          = 'LINE_ITEM'
+      PROMOTED_ACCOUNT   = 'PROMOTED_ACCOUNT'
       PROMOTED_TWEET     = 'PROMOTED_TWEET'
       ORGANIC_TWEET      = 'ORGANIC_TWEET'
       MEDIA_CREATIVE     = 'MEDIA_CREATIVE'
@@ -143,7 +144,10 @@ module TwitterAds
     end
 
     module Optimizations
+      APP_CLICKS          = 'APP_CLICKS'
+      APP_INSTALLS        = 'APP_INSTALLS'
       DEFAULT             = 'DEFAULT'
+      ENGAGEMENTS         = 'ENGAGEMENTS'
       WEBSITE_CONVERSIONS = 'WEBSITE_CONVERSIONS'
     end
 
@@ -218,11 +222,6 @@ module TwitterAds
       HASHTAG = 'HASHTAG'
     end
 
-    module AudienceDefinition
-      TARGETING_CRITERIA = 'TARGETING_CRITERIA'
-      KEYWORD_AUDIENCE = 'KEYWORD_AUDIENCE'
-    end
-
     module LookalikeExpansion
       DEFINED = 'DEFINED'
       EXPANDED = 'EXPANDED'
@@ -233,5 +232,11 @@ module TwitterAds
       PUBLISHED = 'PUBLISHED'
       SCHEDULED = 'SCHEDULED'
     end
+
+    module TimelineType
+      ALL = 'ALL'
+      NULLCAST = 'NULLCAST'
+      ORGANIC = 'ORGANIC'
+    end
   end
 end

data/lib/twitter-ads/error.rb

@@ -59,18 +59,7 @@ module TwitterAds
 
   # Server Errors (5XX)
   class ServerError < Error; end
-
-  class ServiceUnavailable < ServerError
-    attr_reader :retry_after
-
-    def initialize(object)
-      super object
-      if object.headers['retry-after']
-        @retry_after = object.headers['retry-after']
-      end
-      self
-    end
-  end
+  class ServiceUnavailable < ServerError; end
 
   # Client Errors (4XX)
   class ClientError < Error; end
@@ -80,12 +69,13 @@ module TwitterAds
   class BadRequest < ClientError; end
 
   class RateLimit < ClientError
-    attr_reader :reset_at, :retry_after
+    attr_reader :reset_at
 
     def initialize(object)
       super object
-      @retry_after = object.headers['retry-after']
-      @reset_at = object.headers['rate_limit_reset']
+      header = object.headers.fetch('x-account-rate-limit-reset', nil) ||
+               object.headers.fetch('x-rate-limit-reset', nil)
+      @reset_at = header.first.to_i
       self
     end
   end

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

@@ -71,8 +71,37 @@ module TwitterAds
       token    = OAuth::AccessToken.new(consumer, @client.access_token, @client.access_token_secret)
       request.oauth!(consumer.http, consumer, token)
 
+      handle_rate_limit = @client.options.fetch(:handle_rate_limit, false)
+      retry_max         = @client.options.fetch(:retry_max, 0)
+      retry_delay       = @client.options.fetch(:retry_delay, 1500)
+      retry_on_status   = @client.options.fetch(:retry_on_status, [500, 503])
+      retry_count       = 0
+      retry_after       = nil
+
       write_log(request) if @client.options[:trace]
-      response = consumer.http.request(request)
+      while retry_count <= retry_max
+        response = consumer.http.request(request)
+        status_code = response.code.to_i
+        break if status_code >= 200 && status_code < 300
+
+        if handle_rate_limit && retry_after.nil?
+          rate_limit_reset = response.fetch('x-account-rate-limit-reset', nil) ||
+                             response.fetch('x-rate-limit-reset', nil)
+          if status_code == 429
+            retry_after = rate_limit_reset.to_i - Time.now.to_i
+            @client.logger.warn('Request reached Rate Limit: resume in %d seconds' % retry_after)
+            sleep(retry_after + 5)
+            next
+          end
+        end
+
+        if retry_max.positive?
+          break unless retry_on_status.include?(status_code)
+          sleep(retry_delay / 1000)
+        end
+
+        retry_count += 1
+      end
       write_log(response) if @client.options[:trace]
 
       Response.new(response.code, response.each {}, response.body)

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

@@ -9,9 +9,7 @@ module TwitterAds
     attr_reader :code,
                 :headers,
                 :raw_body,
-                :body,
-                :rate_limit_remaining,
-                :rate_limit_reset
+                :body
 
     # Creates a new Response object instance.
     #
@@ -37,16 +35,6 @@ module TwitterAds
         @body = raw_body
       end
 
-      if headers.key?('x-rate-limit-reset')
-        @rate_limit           = headers['x-rate-limit-limit'].first
-        @rate_limit_remaining = headers['x-rate-limit-remaining'].first
-        @rate_limit_reset     = headers['x-rate-limit-reset'].first.to_i
-      elsif headers.key?('x-cost-rate-limit-reset')
-        @rate_limit           = headers['x-cost-rate-limit-limit'].first
-        @rate_limit_remaining = headers['x-cost-rate-limit-remaining'].first
-        @rate_limit_reset     = Time.at(headers['x-cost-rate-limit-reset'].first.to_i)
-      end
-
       self
     end
 

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

@@ -5,15 +5,35 @@ require 'zlib'
 require 'open-uri'
 
 module TwitterAds
-  module Analytics
+  class Analytics
 
+    include TwitterAds::DSL
+    include TwitterAds::Resource
     include TwitterAds::Enum
 
+    attr_reader :account
+
+    property :id, read_only: true
+    property :id_str, read_only: true
+    property :status, read_only: true
+    property :url, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :expires_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+    property :start_time, type: :time, read_only: true
+    property :end_time, type: :time, read_only: true
+
+    property :entity, read_only: true
+    property :entity_ids, read_only: true
+    property :placement, read_only: true
+    property :granularity, read_only: true
+    property :metric_groups, read_only: true
+
     ANALYTICS_MAP = {
       'TwitterAds::Campaign' => Entity::CAMPAIGN,
       'TwitterAds::LineItem' => Entity::LINE_ITEM,
       'TwitterAds::OrganicTweet' => Entity::ORGANIC_TWEET,
-      'TwitterAds::Creative::PromotedAccount' => Entity::ACCOUNT,
+      'TwitterAds::Creative::PromotedAccount' => Entity::PROMOTED_ACCOUNT,
       'TwitterAds::Creative::PromotedTweet' => Entity::PROMOTED_TWEET,
       'TwitterAds::Creative::MediaCreative' => Entity::MEDIA_CREATIVE
     }.freeze
@@ -25,42 +45,38 @@ module TwitterAds
     RESOURCE_ACTIVE_ENTITIES  = "/#{TwitterAds::API_VERSION}/" +
                                 'stats/accounts/%{account_id}/active_entities' # @api private
 
-    def self.included(klass)
-      klass.send :include, InstanceMethods
-      klass.extend ClassMethods
+    def initialize(account)
+      @account = account
+      self
     end
 
-    module InstanceMethods
-
-      # Pulls a list of metrics for the current object instance.
-      #
-      # @example
-      #   metric_groups = [:promoted_tweet_timeline_clicks, :promoted_tweet_search_clicks]
-      #   object.stats(metrics)
-      #
-      # @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).
-      #
-      # @return [Array] The collection of stats requested.
-      #
-      # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
-      # @since 1.0.0
-      def stats(metric_groups, opts = {})
-        self.class.stats(account, [id], metric_groups, opts)
-      end
-
+    # Pulls a list of metrics for the current object instance.
+    #
+    # @example
+    #   metric_groups = [MetricGroup::MOBILE_CONVERSION, MetricGroup::ENGAGEMENT]
+    #   object.stats(metrics)
+    #
+    # @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).
+    #
+    # @return [Array] The collection of stats requested.
+    #
+    # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
+    # @since 1.0.0
+    def stats(metric_groups, opts = {})
+      self.class.stats(account, [id], metric_groups, opts)
     end
 
-    module ClassMethods
+    class << self
 
       # Pulls a list of metrics for a specified set of object IDs.
       #
       # @example
       #   ids = ['7o4em', 'oc9ce', '1c5lji']
-      #   metric_groups = [MetricGroups.MOBILE_CONVERSION, MetricGroups.ENGAGEMENT]
+      #   metric_groups = [MetricGroup::MOBILE_CONVERSION, MetricGroup::ENGAGEMENT]
       #   object.stats(account, ids, metric_groups)
       #
       # @param account [Account] The Account object instance.
@@ -70,7 +86,7 @@ module TwitterAds
       # @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 [String] :placement The placement of entity (default: ALL_ON_TWITTER).
       #
       # @return [Array] The collection of stats requested.
       #
@@ -108,7 +124,7 @@ module TwitterAds
       #
       # @example
       #   ids = ['7o4em', 'oc9ce', '1c5lji']
-      #   metric_groups = [MetricGroups.MOBILE_CONVERSION, MetricGroups.ENGAGEMENT]
+      #   metric_groups = [MetricGroup::MOBILE_CONVERSION, MetricGroup::ENGAGEMENT]
       #   object.create_async_job(account, ids, metric_groups)
       #
       # @param account [Account] The Account object instance.
@@ -118,16 +134,17 @@ module TwitterAds
       # @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).
+      # @option opts [String] :placement The placement of entity (default: ALL_ON_TWITTER).
+      # @option opts [String] :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
+      # @since 1.0.0
 
       def create_async_job(account, ids, metric_groups, opts = {})
         # set default metric values
+        entity            = opts.fetch(:entity, name)
         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)
@@ -143,7 +160,7 @@ module TwitterAds
           start_time: TwitterAds::Utils.to_time(start_time, granularity, start_utc_offset),
           end_time: TwitterAds::Utils.to_time(end_time, granularity, end_utc_offset),
           granularity: granularity.to_s.upcase,
-          entity: ANALYTICS_MAP[name],
+          entity: ANALYTICS_MAP[entity],
           placement: placement,
           country: country,
           platform: platform
@@ -153,19 +170,18 @@ module TwitterAds
         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]
+        TwitterAds::Analytics.new(account).from_response(response.body[:data], response.headers)
       end
 
       # Check async job status.
       # GET /#{TwitterAds::API_VERSION}/stats/jobs/accounts/:account_id
       #
       # @example
-      #   TwitterAds::LineItem.check_async_job_status(account, job_id: '1357343438724431305')
+      #   TwitterAds::LineItem.check_async_job_status(account, job_ids: ['1357343438724431305'])
       #
       # @param account [Account] The Account object instance.
-      # @option opts [String] :job_id The starting time to use (default: 7 days ago).
+      # @option opts [Array] :job_ids A collection of job IDs to fetch.
       #
       # @return A cursor of job statuses
 
@@ -173,18 +189,18 @@ module TwitterAds
         # set default values
         job_ids = opts.fetch(:job_ids, nil)
         params = {}
-        params[:job_ids] = Array.wrap(job_ids).join(',') if job_ids
+        params[:job_ids] = job_ids.join(',') if job_ids
 
         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])
+        Cursor.new(TwitterAds::Analytics, 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)
+      #   response_data = TwitterAds::LineItem.fetch_async_job_data(account, data_url)
       #
       # @param data_url [String] The URL from the successful completion of an async job.
       #
@@ -209,21 +225,57 @@ module TwitterAds
         end
       end
 
+      # Retrieve details about which entities' analytics metrics
+      # have changed in a given time period.
+      #
+      # @example
+      #   time = Time.now
+      #   utc_offset = '+09:00'
+      #   start_time = time - (60 * 60 * 24) # -1 day
+      #   end_time = time
+      #   active_entities = TwitterAds::LineItem.active_entities(
+      #     account,
+      #     line_item_ids: %w(exrfs),
+      #     start_time: start_time,
+      #     end_time:   end_time,
+      #     utc_offset: utc_offset,
+      #     granularity: :day)
+      #
+      # @param account [Account] The Account object instance.
+      # @param entity [String] The entity type to retrieve data for.
+      # @param start_time [Time] Scopes the retrieved data to the specified start time.
+      # @param end_time [Time] Scopes the retrieved data to the specified end time.
+      # @option opts [Array] :campaign_ids A collection of IDs to be fetched.
+      # @option opts [Array] :funding_instrument_ids A collection of IDs to be fetched.
+      # @option opts [Array] :line_item_ids A collection of IDs to be fetched.
+      #
+      # @return A list of entity details.
+      #
+      # @see https://developer.twitter.com/en/docs/ads/analytics/api-reference/active-entities
+
       def active_entities(account, start_time:, end_time:, **opts)
-        entity_type = name
+        entity            = opts.fetch(:entity, name)
         granularity       = opts.fetch(:granularity, nil)
         start_utc_offset  = opts[:start_utc_offset] || opts[:utc_offset]
         end_utc_offset    = opts[:end_utc_offset] || opts[:utc_offset]
 
-        if entity_type == 'OrganicTweet'
-          raise "'OrganicTweet' not support with 'active_entities'"
+        if entity == 'OrganicTweet'
+          raise "'OrganicTweet' is not supported with 'active_entities'"
         end
 
         params = {
-          entity: ANALYTICS_MAP[entity_type],
+          entity: ANALYTICS_MAP[entity],
           start_time: TwitterAds::Utils.to_time(start_time, granularity, start_utc_offset),
           end_time: TwitterAds::Utils.to_time(end_time, granularity, end_utc_offset)
-        }.merge!(opts)
+        }
+
+        opts.each { |k, v|
+          params[k] = if v.instance_of?(Array)
+                        v.join(',')
+                      else
+                        v
+                      end
+        }
 
         resource = self::RESOURCE_ACTIVE_ENTITIES % { account_id: account.id }
         response = Request.new(account.client, :get, resource, params: params).perform