API Reference

This reference follows the Google Publisher Tag documentation conventions, and uses TypeScript notation to describe types. Please refer to the GPT documentation for details.

Type Definitions

FuseId

An identifier provided by Publift that determines which ad types will be inserted into a Zone

Example:

type FuseId = string;

const myFuse: FuseId = '2142583934';

TargetingPair

interface TargetingPair {
  key: string;
  value: TargetingValue;
}

Example:

{
  "key": "weather",
  "value": [
    "sunny",
    "hot"
  ]
}

TargetingValue

The value of a targeting key. Either a string, or an array of strings.

type TargetingValue = string | string[];

const valueSingle: TargetingValue = 'hot';
const valueMultiple: TargetingValue = ['hot', 'sunny'];

Deprecations

The following functions are deprecated

Variables

Summary

fusetag.que

The fuse command queue used for safe asynchronous execution of fuse-related calls. By executing all commands as callbacks pushed to a queue, publishers guard against errors caused by fuse API calls before the script has loaded. As the final step in the fuse initialisation process, all queued callbacks are executed in the order they were pushed, and the push function is replaced so that subsequent calls execute synchronously.

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.que.push(function() {
            fusetag.setTargeting('food', 'banana');
            fusetag.setTargeting('weather', ['sunny', 'hot']);
      });
</script>

Functions

Summary

fusetag.activateZone

activateZone(id: ZoneDivId)

Signals to Fuse that a zone with a manual-activation condition can be activated. The newly activated zone will be immediately eligible for auction.

Note the activation may not complete if additional conditions are attached to the unit. Please discuss with your Publift account manager.

fusetag.pageInit

pageInit(options?: PageInitOptions)

interface PageInitOptions {
  // Page-level targeting (applies to all slots by default)
  // passed to Prebid and GPT
  pageTargets?: TargetingPair[];

  // Fuse Ids which must be present in the DOM before
  // the auction will commence
  blockingFuseIds?: FuseId[];

  // Number of milliseconds the auction is blocked waiting for
  // blockingFuseIds before it times out and proceeds with what's available.
  // If not supplied, Fuse will select an appropriate default depending on
  // factors such as device type
  blockingTimeout?: number;
}

Signals to fuse that a new page has initialised. This function may be called even before the page DOM has loaded content. It causes Fuse to immediately run a DOM-scan and auction, unless there are outstanding initialisation conditions in which case the scan and auction will be deferred until the initialisation phase.

In a Dynamic Site context, it is greatly preferred to supply the blockingFuseIds option. This provides Fuse with an additional initialisation constraint: a list of FuseIds which each must have at least one Zone registered for the condition to be satisfied.

With this approach, Dynamic Sites notify Fuse at the start of the page initialisation process which FuseIds will be present on the page, and Fuse defers the first auction until all are available.

A timeout ensures Fuse does not wait indefinitely for missing FuseIds to be registered. The default value is automatically selected based on factors such as device type. You may override this value with the blockingTimeout option, but this is generally recommended for testing only. Please discuss with the onboarding team if you feel the default should be greater or shorter.

It is usually best to err on the side of too-short a timeout, because the impact is simply additional auctions and missed roadblocks. By contrast, too-long a timeout causes an excessive delay in ads, which is likely worse for yield overall.

Dynamic Site navigation

Dynamic Sites sometimes allow navigation to different URLs without a browser refresh. For example, by dynamically replacing some or all of the DOM and using a browser API to change the URL in the address bar.

Typically when this happens, some Zones are removed from the page and others are added. Zones that persist during page navigation are eligible to refresh.

If pageInit is not used during Dynamic Site navigation, the newly added Zones may be auctioned independently rather than as a batch. Multiple auctions are slower, particularly on mobile devices, and also prevents GAM roadblocks from operating correctly.

During page navigation, the timeout is measured from when the pageInit call is made. Fuse will again select an appropriate timeout, typically shorter than during the initial page load.

fusetag.registerAll

registerAll()

Scans the DOM, and registers all unregistered Zones. In most cases, calling this directly will cause the auction to run, provided the tag is initialised and the registered zones are Active.

fusetag.registerZone

registerZone(id: ZoneDivId)

Scans the DOM for a Zone with element ID exact equal to the specified id parameter, and registers it as a fuse unit, provided it has a valid data-fuse attribute. If the specified Zone has already been registered, the call returns without action.

Once the tag is initialised, calling this function usually causes an auction to start if the registered Zone is active.

fusetag.setTargeting

setTargeting(key: string, value: TargetingValue)

Sets page level targeting with the supplied key/value pair. Overrides any previously defined page-level targeting for the specified key.

Targeting must be set before the auction starts, else it will not be used in the auction.

fusetag.setAllowRefreshCallback

setAllowRefreshCallback(callback: (slotDivId: SlotElementId) => boolean)

Sets callback which runs before slot refresh. if callback return true then refresh is allowed to run, if returned false then refresh does not happen. Can be used only in fusetag.que

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.que.push(function() {
          fusetag.setAllowRefreshCallback(function(slotId) {console.log(slotId); return false;})
      });
</script>