class TwitterAds::Analytics

Constants

ANALYTICS_MAP
RESOURCE_ACTIVE_ENTITIES
RESOURCE_ASYNC_STATS
RESOURCE_STATS

Attributes

account[R]

Public Class Methods

active_entities(account, start_time:, end_time:, **opts) click to toggle source

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 developer.twitter.com/en/docs/ads/analytics/api-reference/active-entities

# File lib/twitter-ads/resources/analytics.rb, line 257
def active_entities(account, start_time:, end_time:, **opts)
  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 == 'OrganicTweet'
    raise "'OrganicTweet' is not supported with 'active_entities'"
  end

  params = {
    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)
  }

  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
  response.body[:data]
end
check_async_job_status(account, opts = {}) click to toggle source

Check async job status. GET /#{TwitterAds::API_VERSION}/stats/jobs/accounts/:account_id

@example

TwitterAds::LineItem.check_async_job_status(account, job_ids: ['1357343438724431305'])

@param account [Account] The Account object instance. @option opts [Array] :job_ids A collection of job IDs to fetch.

@return A cursor of job statuses

# File lib/twitter-ads/resources/analytics.rb, line 189
def check_async_job_status(account, opts = {})
  # set default values
  job_ids = opts.fetch(:job_ids, nil)
  params = {}
  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(TwitterAds::Analytics, request, init_with: [account])
end
create_async_job(account, ids, metric_groups, opts = {}) click to toggle source

Create an asynchronous analytics job for a given ads account. A job_id is returned, which you can use to poll the GET stats/jobs/accounts/:account_id endpoint, checking until the job is successful.

@example

ids = ['7o4em', 'oc9ce', '1c5lji']
metric_groups = [MetricGroup::MOBILE_CONVERSION, MetricGroup::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 [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 dev.twitter.com/ads/analytics/metrics-and-segmentation @since 1.0.0

# File lib/twitter-ads/resources/analytics.rb, line 146
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)
  start_utc_offset  = opts[:start_utc_offset] || opts[:utc_offset]
  end_utc_offset    = opts[:end_utc_offset] || opts[:utc_offset]
  placement         = opts.fetch(:placement, Placement::ALL_ON_TWITTER)
  segmentation_type = opts.fetch(:segmentation_type, nil)
  country = opts.fetch(:country, nil)
  platform = opts.fetch(:platform, nil)

  params = {
    metric_groups: metric_groups.join(','),
    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[entity],
    placement: placement,
    country: country,
    platform: platform
  }.compact

  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 }
  response = Request.new(account.client, :post, resource, params: params).perform
  TwitterAds::Analytics.new(account).from_response(response.body[:data], response.headers)
end
fetch_async_job_data(data_url) click to toggle source

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, data_url)

@param data_url [String] The URL from the successful completion of an async job.

@return A cursor of job statuses

# File lib/twitter-ads/resources/analytics.rb, line 210
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
new(account) click to toggle source
# File lib/twitter-ads/resources/analytics.rb, line 49
def initialize(account)
  @account = account
  self
end
stats(account, ids, metric_groups, opts = {}) click to toggle source

Pulls a list of metrics for a specified set of object IDs.

@example

ids = ['7o4em', 'oc9ce', '1c5lji']
metric_groups = [MetricGroup::MOBILE_CONVERSION, MetricGroup::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 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 [String] :placement The placement of entity (default: ALL_ON_TWITTER).

@return [Array] The collection of stats requested.

@see dev.twitter.com/ads/analytics/metrics-and-segmentation @since 1.0.0

# File lib/twitter-ads/resources/analytics.rb, line 97
def stats(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 - (60 * 60 * 24 * 7)) # 7 days ago
  granularity       = opts.fetch(:granularity, :hour)
  start_utc_offset  = opts[:start_utc_offset] || opts[:utc_offset]
  end_utc_offset    = opts[:end_utc_offset] || opts[:utc_offset]
  placement         = opts.fetch(:placement, Placement::ALL_ON_TWITTER)

  params = {
    metric_groups: metric_groups.join(','),
    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],
    placement: placement
  }

  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

Public Instance Methods

stats(metric_groups, opts = {}) click to toggle source

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 dev.twitter.com/ads/analytics/metrics-and-segmentation @since 1.0.0

# File lib/twitter-ads/resources/analytics.rb, line 70
def stats(metric_groups, opts = {})
  self.class.stats(account, [id], metric_groups, opts)
end