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.

The terms "ad unit containers" and "placements" can be used interchangeably, as they both refer to the spaces that hold the ad units rendered within them.

`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: [] };

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!');
});

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

Once Optimize is fully initialized, window.optimize.queue.push will act as a function that executes any queued commands immediately. It's crucial to use this function for queuing commands, as window.optimize.queue may not always be an Array.

`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.');
}

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[] }

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.

Additionally, while most uses of window.optimize.customTargeting.push in the Usage blocks above follow a targeting update call with one of the manual ad-loading functions, publishers who have a refresh interval set by BuySellAds' ad operations teams—and who do not require manual management of ad loading—can still utilize window.optimize.customTargeting.push. Optimize will automatically apply the latest custom targeting each time it refreshes.

`push`

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

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

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

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']);

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

`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();
});

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`

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

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']);

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

`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();
});

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.

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

`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();
});

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.

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