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;

  // Optional AFS parameters to use if AFS integration is enabled
  afsPageParams?: {
    query: string;
    page?: string;
    styleId?: string;
  };
}

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

fusetag.onTagInitialised(callback: () => void): 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 execute synchronously. Fuse triggers this event before attempting to run the first auction, so the callback is not guaranteed to be processed before the first auction starts.

Recommended (use the command queue):

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  fusetag.que.push(function () {
    // Fuse has finished initialising and the queue is being flushed.
    // Put any initialisation code here.
    console.log('Fuse has initialised');
  });
</script>

Alternative (wrap onTagInitialised in the queue):

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

fusetag.onSlotsInitialised

fusetag.onSlotsInitialised(callback: () => void): 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.que.push(function () {
    fusetag.onSlotsInitialised(function () {
      console.log('Slots have initialised');
    });
  });
</script>

fusetag.onSlotInitialised

fusetag.onSlotInitialised(callback: () => void): 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.que.push(function () {
    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>

fusetag.setAfsExtractPageParams

setAfsExtractPageParams(callback: () => AfsPageParams)

interface AfsPageParams {
  query: string;
  page?: string;
  styleId?: string;
}

This method is only needed if your site has set up an integration with AdSense for Search (AFS). The method setAfsExtractPageParams allows you to specify a callback function that extracts page parameters from the page for AFS targeting purposes. This function is only needed if the site’s AFS integration is more complex than the default setup, and should typically be configured in coordination with your Publift account manager.

See also the afsPageParams option of the pageInit function, which provides an alternative way to specify AFS page parameters without needing a custom callback function.

Example:

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  fusetag.que.push(function () {
    fusetag.setAfsExtractPageParams(function () {
      // Example implementation that extracts AFS page parameters from the URL query string
      const urlParams = new URLSearchParams(window.location.search);
      return {
        query: urlParams.get('afs_query') || '',
        page: urlParams.get('afs_page') || undefined,
        styleId: urlParams.get('afs_styleId') || undefined,
      };
    });
  });
</script>

fusetag.resetAfs

resetAfs(params: AfsPageParams)

interface AfsPageParams {
  query: string;
  page?: string;
  styleId?: string;
}

This method is only needed if your site has set up an integration with AdSense for Search (AFS). Calling this method resets all AFS-related states in fuse and applies new AFS targeting parameters, clearing any previously set AFS configurations. This function is typically used in Dynamic Site contexts when navigating between pages with different AFS parameters, and should be configured in coordination with your Publift account manager if the site’s AFS integration is more complex than the default setup.

See also the afsPageParams option of the pageInit function, which provides an alternative way to specify AFS page parameters without needing a custom callback function.

Example:

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  fusetag.que.push(function () {
    fusetag.resetAfs({
      query: 'laptop computers',
      page: '1',
      styleId: '1234567890',
    });
  });
</script>

fusetag.setOptableEID

fusetag.setOptableEID(eid: string, isHashed?: boolean): void

This function is only relevant for sites that have set up an integration with Optable, a platform that provides bid enrichment services.

Sets the Optable EID (Extended Identifier) for the page. The EID is typically a user identifier such as a hashed email address that allows Optable to recognize users across different platforms and devices for bid enrichment purposes.

Parameters:

• eid (string): The user identifier to set. This can be either a plain text email address or a pre-hashed value, depending on the isHashed parameter. When passing a pre-hashed value, it must be a SHA-256 hex digest of the email address after lowercasing and trimming whitespace.
• isHashed (boolean, optional): When true, the eid value is treated as already hashed and is passed to Optable without additional hashing. When false or omitted, the eid value is automatically hashed before being sent to the Optable platform. Defaults to false.

Timing: This function should be called as soon as the EID value is available, and before the first auction starts, to ensure that the EID is included in all bid requests.

Dynamic Sites: If the EID value may change during navigation (e.g., user login/logout), call this function with the new EID value whenever it changes to ensure the most up-to-date identifier is used.

This function should be used in coordination with your Publift account manager to ensure it is implemented correctly based on your specific setup and requirements.

Example (plain text email — hashed automatically):

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  fusetag.que.push(function () {
    // Pass in the user's email as the EID, if available. The email will be hashed before being sent to Optable.
    if (window.__userEmail) {
      fusetag.setOptableEID(window.__userEmail);
    }
  });
</script>

Example (pre-hashed email — skips hashing):

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  fusetag.que.push(function () {
    // Pass in a pre-hashed email (SHA-256 hex digest of the lowercased, trimmed email).
    // Set isHashed to true to skip internal hashing.
    if (window.__hashedUserEmail) {
      fusetag.setOptableEID(window.__hashedUserEmail, true);
    }
  });
</script>

fusetag.setForceSafeFrames

fusetag.setForceSafeFrames(force: boolean): void

Forces the use of SafeFrames for all ads on the page. SafeFrames are a managed API framework that creates a container around HTML content served to a webpage and establishes a communication channel between the webpage and the served content.

For additional background, see the Google Ad Manager SafeFrame Help Center article.

This Fuse method wraps GPT’s PubAdsService.setForceSafeFrame API.

Parameters:

• force (boolean): When true, all ad creatives will be rendered inside SafeFrame containers, regardless of whether the advertiser has opted to use SafeFrames. When false, SafeFrame rendering follows the default Google Ad Manager behavior.

This setting applies to all ad slots on the page and should be called before ads are rendered.

Important: Forcing SafeFrames can have a significant impact on ad revenue. Please speak to your Publift account manager before enabling this feature to ensure it is appropriate for your setup.

Example:

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  fusetag.que.push(function () {
    // Force all ads to render in SafeFrames before ad setup runs
    fusetag.setForceSafeFrames(true);
  });
</script>

fusetag.isForceSafeFrames

fusetag.isForceSafeFrames(): boolean

Returns the current status of whether SafeFrames are forced for all ads on the page.

Returns: true if SafeFrames are forced, false otherwise.

See setForceSafeFrames for details on enabling this feature and important considerations around revenue impact.

Example:

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  fusetag.que.push(function () {
    const forceSafeFrames = fusetag.isForceSafeFrames();
    console.log('Force SafeFrames enabled:', forceSafeFrames);
  });
</script>

H5 Gaming Interstitial Ads - Complete Example

H5 interstitial ads are full-screen ad formats designed for HTML5 gaming websites that display between game levels or at natural breakpoints. Here’s a complete example showing all methods together:

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  let interstitialReady = false;

  fusetag.que.push(function () {
    // Step 1: Register callback for when ad is ready
    fusetag.onH5InterstitialReady(function (zoneCode) {
      interstitialReady = true;
      console.log('H5 Interstitial ready: ' + zoneCode);
      // Ad is now ready; call fusetag.displayH5Interstitial() later at an appropriate time
    });

    // Step 2: Register callback for when ad is closed
    fusetag.onH5InterstitialClosed(function (zoneCode) {
      interstitialReady = false;
      console.log('H5 Interstitial closed: ' + zoneCode);
      // TODO: Implement your game-specific logic here
      // resumeGame();  // Resume your game state
      // nextLevel();   // Advance to next level
    });

    // Step 3: Register and load the ad
    fusetag.registerH5Interstitial('h5_interstitial');
  });

  // Step 4: Call displayH5Interstitial() when transitioning between levels
  function onLevelComplete() {
    if (interstitialReady) {
      fusetag.que.push(function () {
        fusetag.displayH5Interstitial();
      });
    }
  }
</script>

Best Practices:

• Register onH5InterstitialReady and onH5InterstitialClosed callbacks before calling registerH5Interstitial()
• Call displayH5Interstitial() at natural game breakpoints (level transitions, pause screens)
• Verify the ad is ready before calling displayH5Interstitial() to avoid displaying nothing
• Limit ad frequency (recommended: 3+ minutes between displays)
• In strict CMP mode, if personalization consent is denied, the ready callback will not be invoked

fusetag.registerH5Interstitial

registerH5Interstitial(zoneCode: string)

Registers and loads an H5 gaming interstitial ad.

Parameters:

• zoneCode - The zone code/ID for the H5 interstitial zone

Behavior:

• Initializes the H5 interstitial slot
• Waits for CMP consent if configured (in strict CMP mode, the ad will not load if personalization is denied)
• Calls GPT to create the out-of-page slot
• Triggers the onH5InterstitialReady callback when the ad is ready
• You must call displayH5Interstitial() to show the ad when appropriate (e.g., at level transitions)

fusetag.onH5InterstitialReady

onH5InterstitialReady(callback: (zoneCode: string) => void)

Registers a callback to be invoked when the H5 interstitial ad is ready to display. The callback receives the zone code as a parameter.

Important: This callback must be registered before calling registerH5Interstitial(), otherwise you may miss the ready event.

fusetag.displayH5Interstitial

displayH5Interstitial()

Displays the H5 interstitial ad to the user. This method must be called manually at an appropriate time in your game (e.g., level transitions, pause screens) after the ad is ready.

Important:

• Call this method only after the onH5InterstitialReady callback has been invoked
• Do NOT call this automatically in the ready callback - call it when you want to show the ad
• Verify the ad is ready before calling to avoid displaying nothing

fusetag.onH5InterstitialClosed

onH5InterstitialClosed(callback: (zoneCode: string) => void)

Registers a callback to be invoked when the H5 interstitial ad is closed by the user. The callback receives the zone code as a parameter.

This is useful for resuming game state, advancing to the next level, or performing other actions after the ad is dismissed.

H5 Rewarded Ads - Complete Example

H5 rewarded ads provide in-game rewards or benefits to users who watch them, typically used to grant extra lives, coins, or other game currency. Here’s a complete example showing all methods together:

<script>
  const fusetag = window.fusetag || (window.fusetag = { que: [] });
  let rewardedAdReady = false;

  fusetag.que.push(function () {
    // Step 1: Register callback for when ad is ready
    fusetag.onRewardedReady(function (zoneCode) {
      rewardedAdReady = true;
      console.log('Rewarded ad ready: ' + zoneCode);
      // TODO: Implement your UI update logic here
      // enableWatchAdButton();  // Enable your "Watch Ad" button
    });

    // Step 2: Register callback for when reward is earned
    fusetag.onRewardedGranted(function (zoneCode, payload) {
      if (payload) {
        console.log('Reward granted: ' + payload.amount + ' ' + payload.type);
        // TODO: Implement your reward logic here
        // grantReward(payload.type, payload.amount);  // Grant coins, lives, etc.
      }
    });

    // Step 3: Register callback for when ad is closed
    fusetag.onRewardedClosed(function (zoneCode) {
      rewardedAdReady = false;
      console.log('Rewarded ad closed: ' + zoneCode);
      // TODO: Implement your game-specific logic here
      // resumeGame();  // Resume your game state
    });

    // Step 4: Pre-load the ad early (e.g., on page load)
    fusetag.registerRewarded('rewarded');
  });

  // Step 5: Display ad when user opts in (e.g., clicks "Watch Ad for Coins" button)
  document.getElementById('watch-ad-btn').addEventListener('click', function () {
    if (rewardedAdReady) {
      fusetag.que.push(function () {
        fusetag.displayRewarded();
      });
    } else {
      console.log('Ad not ready yet');
    }
  });
</script>

Best Practices:

• Register all callbacks (onRewardedReady, onRewardedGranted, onRewardedClosed) before calling registerRewarded()
• Pre-load the ad by calling registerRewarded() early (e.g., on page load or game start)
• Track the ready state in a variable when onRewardedReady fires
• Call displayRewarded() when the user clicks to watch the ad (verify it’s ready first)
• Grant rewards in the onRewardedGranted callback when the reward is earned
• Clearly communicate to users what reward they will receive
• In strict CMP mode, if personalization consent is denied, the ready callback will not be invoked

fusetag.registerRewarded

registerRewarded(zoneCode: string)

Registers and loads an H5 rewarded ad.

Parameters:

• zoneCode - The zone code/ID for the H5 rewarded zone

Behavior:

• Initializes the H5 rewarded slot
• Waits for CMP consent if configured (in strict CMP mode, the ad will not load if personalization is denied)
• Calls GPT to create the out-of-page slot
• Triggers the onRewardedReady callback when the ad is ready
• You must call displayRewarded() when the user opts in to watch the ad

fusetag.onRewardedReady

onRewardedReady(callback: (zoneCode: string) => void)

Registers a callback to be invoked when the H5 rewarded ad is ready to display. The callback receives the zone code as a parameter.

Important: This callback must be registered before calling registerRewarded(), otherwise you may miss the ready event.

fusetag.onRewardedGranted

onRewardedGranted(callback: (zoneCode: string, payload: { type: string; amount: number } | null) => void)

Registers a callback to be invoked when the user earns a reward from watching the ad. The callback receives the zone code and reward payload.

Parameters:

• callback - Function called when the reward is earned
  • zoneCode - The zone code
  • payload - Reward information object or null
    • type - The reward type (e.g., “coins”, “lives”)
    • amount - The reward amount

Note: This callback is fired when the reward is earned, typically after the user watches the ad for a minimum duration. This is where you should grant the reward to the user.

fusetag.displayRewarded

displayRewarded()

Displays the H5 rewarded ad when the user opts in to watch it. This is typically called when the user clicks a button to watch an ad for a reward.

Important:

• Call this method only after the onRewardedReady callback has been invoked
• Verify the ad is ready before calling to avoid displaying nothing
• This should be triggered by user action (e.g., clicking a “Watch Ad for Coins” button)

fusetag.onRewardedClosed

onRewardedClosed(callback: (zoneCode: string) => void)

Registers a callback to be invoked when the H5 rewarded ad is closed by the user. The callback receives the zone code as a parameter.

This callback is useful for resuming game state or updating UI after the ad is dismissed. Rewards should be granted in the onRewardedGranted callback, not here.