BuySellAds Optimize Advanced Functions

The use of the following functions is only necessary if you want more control over how the Optimize ads load on your website. There are two key concepts you should understand when it comes to managing the state of ads.

• Push: You want to "push" ads into the ad unit container each time a new page loads.
• Refresh: You want to "refresh" the ad containers at all other times.

queue#

Return the array of codes that are scheduled to run after window.optimize has been initialized.

Signature#

window.optimize.queue : Array<Command>

• Command: Represents a function or task that will be executed once window.optimize is initialized.

Example#

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

Notes#

To ensure proper functionality, always initialize window.optimize early in your script. Assign an empty queue array to handle cases where the Optimize script doesn't load in time. You can use window.optimize.queue.push to queue the functions you want to execute. After window.optimize is initialized, all queued functions will run automatically.

queue.push#

Push the function you want to execute to an queue that will run after window.optimize has been initialized.

Signature#

window.optimize.queue.push(...commands) : void

Parameters#

...commands : Array<Command>

• ...commands: The tasks to be run when Optimize is fully initialized. A Command is a function that executes a specific operation related to the Optimize feature.

Example#

// When initializing the web page
window.optimize = window.optimize || { queue: [] }

window.optimize.queue.push(() => {
  // Example of pushing an ad to a specific container
  window.optimize.push('bsa-zone_123456789-0_123456')

  // Log when Optimize has fully initialized
  console.log('Optimize has fully initialized!')
})

Notes#

To ensure that Optimize functions properly, all calls to the following methods must be made within a command pushed to window.optimize.queue:

• window.optimize.addEventListener
• window.optimize.customTargeting.push
• window.optimize.push
• window.optimize.pushAll
• window.optimize.refresh
• window.optimize.refreshAll
• window.optimize.removeEventListener
• window.optimize.stopAutomaticRefresh

isInitialized#

Returns a boolean value indicating whether Optimize has been initialized.

Signature#

window.optimize.isInitialized: boolean

Example#

if (window.optimize.isInitialized) {
  // Execute code to load an ad into a new container
  window.optimize.push('new-ad-container-id')
} else {
  console.log('Optimize is not initialized yet.')
}

Notes#

You can use window.optimize.isInitialized to check if Optimize has been initialized, which is particularly useful when you need to execute different code after queuing core functions with window.optimize.queue.push.

Considerations#

• Use window.optimize.queue.push to ensure that your code runs immediately after Optimize has been initialized.
• Use window.optimize.isInitialized to check if Optimize is initialized, allowing you to run your code at any point during the session after initialization.

For instances like displaying a dialog window on the same page with an ad, check the status of isInitialized before attempting to load the ad into the container.

customTargeting#

Allows setting custom targeting parameters for ad requests handled by Google Ad Manager.

Signature#

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

Target Type#

type Target =
  | [string, string | string[]]
  | { key: string; value: string | string[] }

Notes#

Custom targeting parameters are applied at the page-level for future ad requests using Optimize's ad loading functions (push, pushAll, refresh, and refreshAll).

For more information, see the Page-level section of Google's Key-value targeting guide.

customTargeting.push#

Add or modify existing targets in window.optimize.customTargeting.

Signature#

window.optimize.customTargeting.push(...targets: Target[]) : void

Example#

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

window.optimize.queue.push(() => {
  // Array format
  window.optimize.customTargeting.push(
    ['color', 'red'],
    ['size', ['small', 'large']]
  )

  // Object format
  window.optimize.customTargeting.push(
    { key: 'fruit', value: 'apple' },
    { key: 'vehicle', value: ['car', 'bike'] }
  )
})

Notes#

• Can be called multiple times to add or update targeting parameters.
• New values for an existing key will replace the old values.
• Use window.optimize.queue.push to ensure custom targeting is set after Optimize initialization.

push#

Push and load the ads into the empty ad container IDs. For ad containers that already have ads, use the refresh function.

Signature#

window.optimize.push(placementIds) : void

Parameters#

placementIds : string | Array<string>

• placementIds: The ID or IDs of the ad unit container(s) that require new ads to be pushed.

Example#

// 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)
})

Notes#

If you have multiple ad unit containers on a page that share the same Optimize placement, append _<number> to the placement ID provided by your BuySellAds ad operations representative for each additional container.

For instance, with a placement ID of bsa-zone_123456789-0_123456, you can have:

• The main ad unit container: div#bsa-zone_123456789-0_123456
• Cloned ad unit containers: div#bsa-zone_123456789-0_123456_1, etc.

To push ads to these containers, use:

window.optimize.push([
  'bsa-zone_123456789-0_123456',
  'bsa-zone_123456789-0_123456_1',
])

pushAll#

Push and load ads into all the empty ad containers.

Signature#

window.optimize.pushAll() : void

Example#

// 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()
})

Notes#

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.

refresh#

Refresh the target ad container(s) with a new ads.

Signature#

window.optimize.refresh(placementIds) : void

Parameters#

placementIds: string | Array<string>

• placementIds: The ID or IDs of the ad unit container(s) that need to be refreshed.

Example#

// 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)
})

Notes#

If you have multiple ad unit containers on a page that share the same Optimize placement, append _<number> to the placement ID provided by your BuySellAds ad operations representative for each additional container.

For example, with a placement ID of bsa-zone_123456789-0_123456, you can have:

• Base ad unit container: div#bsa-zone_123456789-0_123456
• Cloned ad unit containers: div#bsa-zone_123456789-0_123456_1, etc.

To refresh ads for these containers, use window.optimize.refresh as follows:

window.optimize.refresh([
  'bsa-zone_123456789-0_123456',
  'bsa-zone_123456789-0_123456_1',
])

refreshAll#

Refresh the ads on all the ad containers.

Signature#

window.optimize.refreshAll() : void

Example#

// 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()
})

Notes#

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

stopAutomaticRefresh#

Signature#

window.optimize.stopAutomaticRefresh(placementIds) : void

Parameter#

placementIds : string | Array<string> | undefined

• placementIds: The ID or IDs of the ad unit container(s) that need to stop automatically refreshing. You can leave it undefined if you wish to stop automatic refresh on all ad placements.

Example#

// 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()
})

Notes#

If your Optimize account is set up to automatically refresh ads at predefined intervals, you can use this function to turn off automatic refreshing for a single ad unit, a group of ad units, or all ad units at once.