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 exactly 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 only be used 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>

fusetag.destroySticky

destroySticky()

Removes all sticky widgets from the page.

fusetag.onSlotRenderEnded

onSlotRenderEnded(callback: (e: SlotRenderEndedEvent) => void)

Register a callback to be invoked when a slot has finished rendering. The callback receives an object with the following properties:

interface SlotRenderEndedEvent {
  slotId: string;
  hasCreative: boolean; // true if the slot was filled with an ad creative
  gptEvent: googletag.events.SlotRenderEndedEvent;
}

For the gptEvent property, please refer to the GPT documentation

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.que.push(function() {
          fusetag.onSlotRenderEnded(function(e) {
              console.log('Slot ' + e.slotId + ' has finished rendering. Has creative: ' + e.hasCreative);
          });
      });
</script>

fusetag.onSlotViewable

onSlotViewable(callback: (e: SlotViewableEvent) => void)

Register a callback to be invoked when a slot becomes viewable. The callback receives an object with the following properties:

interface SlotViewableEvent {
  slotId: string;
  gptEvent: googletag.events.ImpressionViewableEvent;
}

For the gptEvent property, please refer to the GPT documentation

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.que.push(function() {
          fusetag.onSlotViewable(function(e) {
              console.log('Slot ' + e.slotId + ' is now viewable.');
          });
      });
</script>

fusetag.onTagInitialised

onTagInitialised(callback: () => void)

Register a callback to be invoked when fuse has finished initialising. At this point all fuse features are available, and the fusetag command queue has been flushed, so subsequent calls will execute synchronously. Fuse triggers this event before attempting to run the first auction, so it is not guaranteed that the callback will be processed before the first auction starts.

This is useful for knowing when fuse has initialised; however, it is recommended to use the fusetag command queue for executing code that depends on fuse initialisation, as any code in the fusetag command queue is guaranteed to execute before the first auction.

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.onTagInitialised(function() {
          console.log('Fuse has initialised');
      });
</script>

fusetag.onSlotsInitialised

onSlotsInitialised(callback: () => void)

Register a callback to be invoked when slots have been registered and initialised. This callback is only called the first time slots are initialised e.g. when the DOM is scanned and slots are registered. Any subsequent calls to registerZone or registerAll that result in new slots being registered and initialised will not trigger this callback again.

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.onSlotsInitialised(function() {
          console.log('Slots have initialised');
      });
</script>

fusetag.onSlotInitialised

onSlotInitialised(callback: () => void)

Register a callback to be invoked when any slot is registered and initialised. This callback is called only once when the first slot is initialised after the callback is registered.

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.onSlotInitialised(function() {
          console.log('A Slot has initialised');
      });
</script>

fusetag.getCurrentBreakpoint

getCurrentBreakpoint(): FuseBreakpointInfo

Returns an object containing information about the current breakpoint. The properties of the returned object are as follows:

type BreakpointName = 'xl' | 'l' | 'm' | 's' | 'xs';

interface FuseBreakpointInfo {
  name: BreakpointName; // the name of the current breakpoint, 'xl', 'l', 'm', 's', or 'xs'
  width: number; // the minimum viewport width threshold for the current breakpoint in pixels
}

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.que.push(function() {
          const breakpointInfo = fusetag.getCurrentBreakpoint();
          console.log('Current breakpoint: ' + breakpointInfo.name + ', width threshold: ' + breakpointInfo.width + 'px');
      });
</script>

The name is one of ‘xl’, ’l’, ’m’, ’s’, or ‘xs’ and corresponds to the breakpoints used for the website. The width property indicates the minimum viewport width threshold in pixels for the current breakpoint (not the current width of the viewport). For example, ‘xs’ always has a width of 0 (meaning it applies to all viewport widths starting from 0px), while a value of 768 for the ’s’ breakpoint means that the ’s’ breakpoint applies when the viewport width is at least 768 pixels, and so on.

This function is useful for debugging the page setup and may be used for targeting or conditionally executing code based on the current breakpoint. Please speak to your account manager if you plan to use this function for these purposes, as there may be better alternatives depending on your specific use case.

fusetag.destroyZone

destroyZone(id: ZoneDivId)

Destroys the ad slot associated with the zone with the specified id, and removes it from the page. This is a destructive action that cannot be undone. It should only be used if you want to permanently remove an ad slot from the page. If you simply want to stop refreshing for the slot or make it inactive, please speak to your account manager about the best configuration or API usage for your specific setup before using this function.

Example:

<script>
      const fusetag = window.fusetag || (window.fusetag = { que: [] });
      fusetag.que.push(function() {
          fusetag.destroyZone('my-zone-id');
      });
</script>