Fuse Tag Documentation

Table of Contents

  1. Overview
  2. Fuse tag flow
  3. FAQ's
    1. How do I set up ad unit refresh on my site?
    2. How does lazy loading work?
    3. How can I set targeting?
    4. For the likes of lazy loading and refresh, when is an ad unit "in view"?
    5. Is the fuse tag asynchronous?
    6. Will the fuse tag slow my site load time down?
    7. How much longer will ads take to load with headerbidding?
    8. Will the fuse tag work with a SPA (single page application)?
    9. Will my viewability drop if I turn on refresh?
    10. Where do I place the <script async src="cdn.publift.com/example></script> tag on my page?
    11. Where do I place the <div data-fuse="1234567890"></div> tags on my page?
    12. Why are no ads showing on my page?
    13. What are the functions available on the window.fusetag object?
    14. Will my CMP (Consent Management Platform) work with the fuse tag?
  4. Implementation
    1. Standard
    2. Advanced (technical)
      1. Infinite Scroll or Programmatic Ad Loading
      2. SPA
      3. Programmatic Refresh

Overview

The fuse tag is Publift's scalable solution of providing headerbidding to publishers of all sizes. We have tried to simplify the implementation as much as possible for the client. A standard (and recommended) implementation generally requires no custom implementations for the client.

Fuse tag flow

The following is a more simplified flow of the fuse tag.

  1. Page is loaded.
  2. Fuse tag executes any functions pushed to fusetag.que prior to the tag being loaded.
  3. Fuse tag finds all divs on page with the attribute data-fuse <div data-fuse="1234567890"></div>.
  4. All units that are not lazy loaded have their Prebid requests sent out.
  5. If unit is lazy loaded and not in view, an 'event listener' is added to the page to wait for it to come in view.
  6. On return of all Prebid bid responses or headerbidding timeout is reached, GPT call is made.

Back to top


FAQ's

How do I set up ad unit refresh on my site?

Refresh can be set at both an account level, and at an ad unit level. If you would like to change or set a custom refresh time for your account or a particular unit, reach out to our friendly Account Management team. If you're interested in how the actual refresh works, check out this FAQ: Will my viewability drop if I turn on refresh?!


How does lazy loading work?

We are able to set any unit to be lazy loaded, what this means is that on the initial page load, the fuse tag will not make ad requests to any of the headerbidding networks or DFP in your account until that particular unit is in view. This helps to reduce page load time, as no extra network calls have to be made, until that particular unit is in view.
For more information about a unit being in view, check out this FAQ: For the likes of lazy loading and refresh, when is an ad unit "in view"?!


How can I set targeting?

Easily! All you have to do is add a simple script tag onto your page that will enable you to set page level targeting. In the example below, you can see that targeting is being set with the key being equal to food and the value being equal to banana.
Check out this What are the functions available on the window.fusetag object?, for more information on the available fuse tag functions. If you are experiencing any difficulty with the setting of targeting, reach out to your account manager, they will be more than willing to help you out.

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

For the likes of lazy loading and refresh, when is an ad unit "in view"?

When defining in view, we have chosen to adopt the defacto standard for viewability (at least 50% of the unit is in view).

Criteria for a unit to be in view:

  1. A user must have the browser window and browser tab open, on the page containing the unit.
  2. The unit must be at least 50% in view.

Is the fuse tag asynchronous?

The fuse tag has been built with asynchronicity in mind at all times. In other words, it is completely non-blocking.

  1. It is loaded asynchronously.
  2. Fetches ads using SRA (single request architecture).
  3. Renders ads asynchronously using Async Rendering.

Will the fuse tag slow my site load time down?

No the fuse tag is completely asynchronous, it will not slow down your page from loading.
For more information, refer to these links: 1 - 2.


How much longer will ads take to load with headerbidding?

As a general standard, we recommend that 1000ms is used for the headerbidding timeout, this means that as soon as Prebid requests bid from all your network partners, it will only wait 1000ms for bid responses to come back, before it sends of the DFP request.


Will the fuse tag work with a SPA (single page application)?

Absolutely, we have built in safe guards to ensure that the fuse tag can handle route changes on SPA's. Let us know if you need a hand with your implementation, as it's a little different for SPA's.


Will my viewability drop if I turn on refresh?

Absolutely not, if anything, it'll go up! If a unit is not in view, it will NOT refresh, not matter the circumstance.
For more information on what "in view" refers to, check out this FAQ: For the likes of lazy loading and refresh, when is an ad unit "in view"?!


Where do I place the <script async src="cdn.publift.com/example></script> tag on my page?

As close to the top of the <head> tag as possible, the fuse tag is asynchronous so it will not block any of the content on your page loading.


Where do I place the <div data-fuse="1234567890"></div> tags on my page?

You place these exactly where you want the ad to show. Be mindful that each and every <div data-fuse="2343"></div> tag that your account manager gives you is unique, you need to be mindful of where you are placing them.


Why are no ads showing on my page?

  1. Have you updated your ads.txt?
  2. Are the fuse slots wrapped in <div> tags?
  3. Is the <script async src="cdn.publift.com/example></script> tag at the top of your <head>?
  4. If you type in fusetag to the developer console in your browser, are you seeing a response?
  5. Ensure that the id's inside each <div data-fuse="1234"> slot are correct.

What are the functions available on the window.fusetag object?

All fusetag functions should be inserted into the fusetag que, this is due to the asynchronous nature of the fuse tag.
To push into the que, you should follow the following:

  var fusetag = fusetag || {que:[]};
fusetag.que.push(function() {
                  // any of the below fuse tag functions.
                })
              

Functions available:

  fusetag.loadFuseSlotById(fuse-slot-id) // This loads a particular slot (useful for infinite scroll and/or SPA's.)
                fusetag.setTargeting('key', 'value'); // Sets page level key value targeting.
                fusetag.setTargeting('key', ['value1', 'value2']) // Sets page level key value targeting, however you can pass in an array of values.
                fusetag.loadFuseSlots(); // This loads all slots on the page, this happens by default, no need to add this.
              

Will my CMP (Consent Management Platform) work with the fuse tag?

If the CMP your site utilises follows the IAB approved CMP framework, then yes. The fuse tag will check for the availability of window.__cmp(). If found, it will wait 8 seconds for a users consent, if no consent is provided, the prebid auction will continue and send a no consent received key value to the networks.


Back to top


Implementation

Standard

During your onboarding with Publift, your account manager will send you an email containing a zip file which has a few text files inside of it. These text files are organised categorically for your page. The following is an example of what is inside of one of these text files:

<!-- HEAD -->
              <script async src="//cdn.publift.com/fuse/tag/2/999/fuse.js"></script>

              <!-- BODY -->
              <!-- 71161633/your-company/home_hrec_1 -->
              <div data-fuse="1234567890"></div>

              <!-- 71161633/your-company/home_hrec_2 -->
              <div data-fuse="987654321"></div>

              <!-- 71161633/your-company/home_hrec_3 -->
              <div data-fuse="159375846"></div>

              <!-- 71161633/your-company/home_hrec_4 -->
              <div data-fuse="279231864"></div>
              

In the above code snippet, you will see at the top there is <script> tag that contains the link to the fuse tag which has been customised for your specific implementation. You will need to make sure that this is included on every page of your site where ads are to be served, it should always be placed in the <head>.
Also in the above code snippet, there a few <div> tags, these are specific to the slots on your page. These need to be placed exactly where the ad layout specifies them to be placed.
Please do not modify these divs, the fuse tag relies on them staying as div tags, and they will not work without the correct id and data-fuse attribute.
It should also be noted that ideally no content (html, javascript, styling) should be placed inside the fuse slot div, it may be overwritten.


Back to top

Advanced (technical)

Infinite Scroll or Programmatic Ad Loading

By programmatic ad loading we are referring to a case where you may want to inject a fuse slot into the DOM based on user interaction, scrolling, etc.

Lets say you have been given the following fuse-slot divs by your account manager:

<!-- 71161633/your-company/home_hrec_3 -->
              <div data-fuse="159375846"></div>

              <!-- 71161633/your-company/home_hrec_4 -->
              <div data-fuse="279231864"></div>
              

If you are going to conditionally load these fuse-slots, you need to remember that the fuse tag will automatically load all non-lazy loaded slots that are on the page at document.readyState === 'complete'.

For each ad to load successfully you need to follow these steps:

  1. Add the fuse-slot div into the DOM, with the right id!
  2. The following javascript is executed

     var fusetag = fusetag || {que: []};
    fusetag.que.push(function() {
      fusetag.loadFuseSlotById(id) // id should be equal to the value of the data-fuse attribute set on the fuse slot div.
    })
                  

This needs to happen for each unit you wish to programmatically load.

Note: you are able to load the same unit more than once.


SPA

It’s hard to cover all possible implementations with single page app’s, however there are a few important characteristics of the fuse tag that should be noted.

Once the fuse tag is loaded and document.readyState === 'complete', it will scan the DOM and locate all divs that contain the attribute data-fuse. It well then make the ad calls for the non-lazy loaded units.

It is recommended that SPA implementations do not hard code the divs containing the data-fuse attribute onto the page. Rather they are programmatically injected onto the page, and then ask the fuse tag to load each of them. This is to protect against any race conditions. However, this will mean that a new DFP request is made for each unit.

It can be tricky when working with SPA’s, if you have any questions, please reach out to Publift’s developer support ( dev-support@publift.com), they will be happy to guide you through your implementation.


Programmatic Refresh

Programmatic refresh refers to the case where you have a particular unit that you would like to refresh based on an action or user input.

The window.fusetag object has a property named refreshSlotByCode. This function has only one parameter, which is the slot code for the unit you would like to refresh. The slot code is in the format fuse-slot-[slotId]-[slotCount].

When the fuse tag has scanned the DOM for any div’s with the attribute fuse-slot, it builds those div’s out and prepares them for headerbidding and DFP. On doing this, it will add an attribute called fuse-slot-code to that same div that has the attribute fuse-slot set on it. The fuse-slot-code added will always be unique, and will always be in the format fuse-slot-code="fuse-slot-[slotId]-[slotCount]. SlotId refers to the id inside of the fuse-slot attribute on the div, and slotCount is a number that increments each time a slot is added for that same slotId.

Example:

Lets say you wanted to programmatically refresh the following fuse-slot:

<div fuse-slot="1234" fuse-slot-code="fuse-slot-1234-1"></div>

You would run the command:

  var fusetag = fusetag || {que: []};
  fusetag.que.push(function() {
    fusetag.refreshSlotByCode('fuse-slot-1234-1')
  })

Back to top