Optimize

Advanced Functions

These added Optimize functions offer a way for website owners who have joined the Optimize program to control how they want to load programmatic ads. Most customers will not need to utilize any of these advanced functions and the standard setup will work. If you have any questions, please get in touch with your Account Manager.

General Notes

Make sure to properly push or refresh the ad unit containers using the ad-loading functions window.optimize.push, window.optimize.pushAll, window.optimize.refresh, and window.optimize.refreshAll from above based on the state of the of the website: Ad unit containers should be "pushed" whenever a new page loads, whereas, the containers should be "refreshed" at all other times. It is important to properly push or refresh as the header bidding ad servers treat pushes and refreshes differently in terms of served ads and revenue.

Though most of the uses of window.optimize.customTargeting.push within the Usage blocks above follow the targeting update call with a call to one of the manual ad-loading functions, publishers who have a refresh interval set by BuySellAds's ad operations teams, but do not require manual management of ad loading through the aforementioned functions, can still use window.optimize.customTargeting.push. Every time that Optimize automatically refreshes, the latest custom targeting will be applied.

isInitialized

window.optimize.isInitialized: bool

When you have a block of code that should run only if Optimize has finished initializing, use window.optimize.isInitialized to check. When you have a command that should run after Optimize has finished initializing regardless of Optimize's current initalization status, use window.optimize.queue.push to queue the command.

queue

window.optimize.queue: Array<Command> | { push: (...Command) => void }

window.optimize = window.optimize || { queue: [] }

Commands can be queued before Optimize has been fully initialized. If you need to queue commands within a script tag before the Optimize script tag or are not able to ensure that window.optimize gets set before your script, initialize window.optimize as noted in the Usage above and use window.optimize.queue.push as defined below. When Optimize has fully initialized, all of the collected commands are run.

queue.push

window.optimize.queue.push(...commands): (...Command) => void

// When initializing the web page
window.optimize = window.optimize || { queue: [] }
// ...later
window.optimize.queue.push(() => console.log('Optimize has fully initialized!'))
window.optimize.queue.push(
  () => console.log('Task #1'),
  () => console.log('Task #2')
)

To ensure that Optimize functions properly, all calls to window.optimize.push, window.optimize.pushAll, window.optimize.refresh, window.optimize.refreshAll, and window.optimize.customTargeting.push (defined below) should happen within a command pushed using this function. When Optimize has been fully initialized, window.optimize.queue.push will become a function that immediately runs any commands passed to it. Make sure you use this function to queue commands since window.optimize.queue will not always be an Array.

Target

[string, (string | Array<string>)] | { key: string, value: (string | Array<string>) }

customTargeting

window.optimize.customTargeting: { push: (...Target) => void }

If you need to set custom targeting, use window.optimize.customTargeting.push as defined below.

customTargeting.push

window.optimize.customTargeting.push(...targets): (...Target) => void

// When initializing the web page
window.optimize = window.optimize || { queue: [] }
// ...later
window.optimize.queue.push(() => {
  // using array format...
  window.optimize.customTargeting.push(
    ['key1', 'value1'],
    ['key2', ['value21', 'value22']]
  )
  // ...or object format
  window.optimize.customTargeting.push(
    { key: 'key1', value: 'value1' },
    { key: 'key2', value: ['value21', 'value22'] }
  )
})

Using this function, you can either add targets to or change existing targets in window.optimize.customTargeting. You may use whichever target format ([key, value] or { key, value }) that fits better with your existing code.

This function should be used within a command passed to window.optimize.queue.push to ensure that Optimize functions properly.

push

window.optimize.push(placementIds): (string | Array<string>) => void

Not to be confused with window.optimize.queue.push or window.optimize.customTargeting.push

// When initializing the web page
window.optimize = window.optimize || { queue: [] }
// ...later
window.optimize.queue.push(() => {
  // (optional) Add custom targeting, then...
  window.optimize.customTargeting.push({ key: 'key1', value: 'value1' })
  // ...push an ad for a single container, and / or...
  window.optimize.push('bsa-zone_123456789-0_123456')
  // ...push an ad for a cloned container, and / or...
  window.optimize.push('bsa-zone_123456789-0_123456_1')
  // ...push ads for multiple containers
  const placementIds = [
    'bsa-zone_123456789-1_123456',
    'bsa-zone_123456789-2_123456',
  ]
  window.optimize.push(placementIds)
})

Run window.optimize.push when you want to push an ad to the ad unit container (see General Notes at the bottom of this document for more information on pushing vs. refreshing). If you want to have multiple ad unit containers on a page that point to same Optimize placement, you can do so by appending _<number> to the end of the placement ID supplied by your BuySellAds ad operations representative for every extra ad unit container. For example, if you have a placement ID of bsa-zone_123456789-0_123456, you can have the base ad unit container (i.e. CSS selector div#bsa-zone_123456789-0_123456) as well as any number of cloned ad unit containers (e.g. CSS selector div#bsa-zone_123456789-0_123456_1) on the page. To push ads for these containers, you'd use window.optimize.push like you would for any other placement(s) (e.g. window.optimize.push(['bsa-zone_123456789-0_123456', 'bsa-zone_123456789-0_123456_1'])).

This function should be used within a command passed to window.optimize.queue.push to ensure that Optimize functions properly.

pushAll

window.optimize.pushAll(): () => void

// When initializing the web page
window.optimize = window.optimize || { queue: [] }
// ...later
window.optimize.queue.push(() => {
  // (optional) Add custom targeting, then...
  window.optimize.customTargeting.push({ key: 'key1', value: 'value1' })
  // ...push ads for all containers with a matching placement
  window.optimize.pushAll()
})

This is a shorthand for running window.optimize.push on all of the placements. This list of placements is maintained by the ad operations team at BuySellAds.

This function should be used within a command passed to window.optimize.queue.push to ensure that Optimize functions properly.

refresh

window.optimize.refresh(placementIds): (string | Array<string>) => void

// When initializing the web page
window.optimize = window.optimize || { queue: [] }
// ...later
window.optimize.queue.push(() => {
  // (optional) Add custom targeting, then...
  window.optimize.customTargeting.push({ key: 'key1', value: 'value1' })
  // ...refresh an ad for a single container, and / or...
  window.optimize.refresh('bsa-zone_123456789-0_123456')
  // ...refresh an ad for a cloned container, and / or...
  window.optimize.refresh('bsa-zone_123456789-0_123456_1')
  // ...refresh ads for multiple containers
  const placementIds = [
    'bsa-zone_123456789-1_123456',
    'bsa-zone_123456789-2_123456',
  ]
  window.optimize.refresh(placementIds)
})

Run window.optimize.refresh when you want to a refresh the ad unit container to retrieve a new ad (see General Notes at the bottom of this document for more information on pushing vs. refreshing). If you want to have multiple ad unit containers on a page that point to same Optimize placement, you can do so by appending _<number> to the end of the placement ID supplied by your BuySellAds ad operations representative for every extra ad unit container. For example, if you have a placement ID of bsa-zone_123456789-0_123456, you can have the base ad unit container (i.e. CSS selector div#bsa-zone_123456789-0_123456) as well as any number of cloned ad unit containers (e.g. CSS selector div#bsa-zone_123456789-0_123456_1) on the page. To refresh ads for these containers, you'd use window.optimize.refresh like you would for any other placement(s) (e.g. window.optimize.refresh(['bsa-zone_123456789-0_123456', 'bsa-zone_123456789-0_123456_1'])).

This function should be used within a command passed to window.optimize.queue.push to ensure that Optimize functions properly.

refreshAll

window.optimize.refreshAll(): () => void

// When initializing the web page
window.optimize = window.optimize || { queue: [] }
// ...later
window.optimize.queue.push(() => {
  // (optional) Add custom targeting, then...
  window.optimize.customTargeting.push({ key: 'key1', value: 'value1' })
  // ...refresh ads for all containers with a matching placement
  window.optimize.refreshAll()
})

This is a shorthand for running window.optimize.refresh on all of the placements. Similar to window.optimize.pushAll, this list of placements is maintained by the ad traffickers at BuySellAds.

This function should be used within a command passed to window.optimize.queue.push to ensure that Optimize functions properly.

stopAutomaticRefresh

window.optimize.stopAutomaticRefresh(placementIds): (string | Array<string> | undefined) => void

// When initializing the web page
window.optimize = window.optimize || { queue: [] }
// ...later
window.optimize.queue.push(() => {
  // turn off automatic refreshes for a single ad unit, and / or...
  window.optimize.stopAutomaticRefresh('bsa-zone_123456789-0_123456')
  // ...turn off automatic refreshes for a set of ad units, or...
  window.optimize.stopAutomaticRefresh([
    'bsa-zone_123456789-0_123456',
    'bsa-zone_123456789-0_123456_1',
  ])
  // ...turn off automatic refreshes for all ad units
  window.optimize.stopAutomaticRefresh()
})

Assuming your specialized instance of Optimize has been set up by ad traffickers at BuySellAds to automatically refresh based on a predefined interval, you can use this function to turn off automatic refreshing for either a single ad unit, a set of ad units, or all ad units at once.