class TwitterAds::CustomAudience

Constants

LIST_TYPES
OPERATIONS
RESOURCE
RESOURCE_COLLECTION
RESOURCE_USERS

Attributes

account[R]

Public Class Methods

create(account, name) click to toggle source

Creates a new custom audience.

@example

audience = CustomAudience.create(account, 'my list')

@param account [Account] The account object instance. @param name [String] The custom audience name.

@since 4.0

@return [CustomAudience] The newly created custom audience instance.

# File lib/twitter-ads/audiences/custom_audience.rb, line 69
def create(account, name)
  audience = new(account)
  params = { name: name }
  resource = RESOURCE_COLLECTION % { account_id: account.id }
  response = Request.new(account.client, :post, resource, params: params).perform
  audience.from_response(response.body[:data])
end
new(account) click to toggle source
# File lib/twitter-ads/audiences/custom_audience.rb, line 51
def initialize(account)
  @account = account
  self
end

Public Instance Methods

delete!() click to toggle source

Deletes the current custom audience instance.

@example

audience.delete!

Note: calls to this method are destructive and irreverisble.

@since 0.3.0

@return [self] Returns the custom audience instance refreshed from the API.

# File lib/twitter-ads/audiences/custom_audience.rb, line 89
def delete!
  resource = RESOURCE % { account_id: account.id, id: id }
  response = Request.new(account.client, :delete, resource).perform
  from_response(response.body[:data])
end
targeted(opts = {}) click to toggle source

Retrieves the entites targeting the current tailored audience instance.

@example

audience.targeted(with_active=true)

@param with_active [bool] Include active/inactive

@since 8.0.0

@return [self] Returns a Cursor instance of the targeted entities.

# File lib/twitter-ads/audiences/custom_audience.rb, line 151
def targeted(opts = {})
  validate_loaded
  params = {}.merge!(opts)
  TargetedTailoredAudience.load(account, id, params)
end
users(params) click to toggle source

This is a private API and requires allowlisting from Twitter.

This endpoint will allow partners to add, update and remove users from a given custom_audience_id. The endpoint will also accept multiple user identifier types per user as well.

@example

custom_audience.users(
  account,
  [
    {
      "operation_type": "Update",
      "params": {
        "effective_at": "2018-05-15T00:00:00Z",
        "expires_at": "2019-01-01T07:00:00Z",
        "users": [
          {
            "twitter_id": [
              "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
            ]
          }
        ]
      }
    }
  ]
)

@param params [JSON object] A hash containing the list of users to be added/removed/updated

@since 4.0

@return success_count, total_count

# File lib/twitter-ads/audiences/custom_audience.rb, line 127
def users(params)
  resource = RESOURCE_USERS % { account_id: account.id, id: id }
  headers = { 'Content-Type' => 'application/json' }
  response = TwitterAds::Request.new(account.client,
                                     :post,
                                     resource,
                                     headers: headers,
                                     body: params.to_json).perform
  success_count = response.body[:data][:success_count]
  total_count = response.body[:data][:total_count]

  [success_count, total_count]
end
validate_loaded() click to toggle source
# File lib/twitter-ads/audiences/custom_audience.rb, line 157
def validate_loaded
  raise ArgumentError.new(
    "Error! #{self.class} object not yet initialized, " \
    "call #{self.class}.load first") if id.nil?
end