Dynamic Site Initialisation

This page describes how to initialise a Dynamic Site. If you’re unsure whether your site is dynamic, see Static or Dynamic Initialisation?.

Summary

  1. Configure your ads.txt file.
  2. Include the fuse.js <script> in your page <head>.
  3. Configure your SPA framework to insert the Zones in the required locations, and register them.
  4. Call the fusetag.pageInit function.
  5. Refresh the browser. If no ads are showing, consult the troubleshooting guide.

Zone Registration

When inserting Zones into a Dynamic Site, it’s strongly recommended set a unique id attribute on the <div>.

After the <div> has been inserted into the DOM, it should be registered using the fusetag.registerZone function, supplying the assigned id attribute as the argument.

Dynamic Sites typically have multiple components, each responsible for inserting one Zone into the DOM, and registering it with Fuse.

The post-insert registration is typically performed via a callback that depends on the web framework. For example:

Please see Zone Registration for further discussion, including optional styling parameters.

Initialisation Process

Initialisation Conditions

Fuse will finalise the initialisation process once the following conditions are satisfied:

  • The CMP consent status has been determined, if CMP is enabled
  • Required 3rd-party scripts have downloaded and initialised

During the finalisation stage:

  • Fuse executes all tasks pushed to fusetag.que
  • The fusetag.que array is updated so that future functions added using the push function execute synchronously.

Triggering the first auction

SPA initialisation is more complex, because components responsible for inserting fuse body tags may not have finished loading when the ‘completed’ or ‘initialised’ Document.readyState states are reached. In that case, fuse scans the DOM prematurely, and will not detect Zones still initialising. This means that additional auctions will need to run for the late Zones, which is slower and bypasses configured GAM roadblocks.

To avoid this problem, the preferred initialisation approach for Dynamic Sites is to disable the automatic DOM scan, and instead signal the page is ready using the fusetag.pageInit function.

As most Dynamic Sites typically involve multiple components initialising independently, the blockingFuseIds parameter allows mandatory FuseIds to be specified at the start of the page load.

If the fusetag.pageInit function was called, the first auction will be deferred until

  • All initialisation conditions are satisfied; AND EITHER
    • A Zone corresponding to each specified blockingFuseIds has been registered; OR
    • The blockingTimeout has been reached.

As an example, the pageInit function could be called from a fixed <script> block in the <head> of the page:

<head>
    <!-- ommitted -->

    <script>
        // Get an initialisation-safe reference to the Fuse Queue
        const fusetag = window.fusetag || (window.fusetag = { que: [] });

        fusetag.que.push(function() {
            fusetag.pageInit({
                // Defer the first auction until FuseIds '1239469485' and '2323123233' are registered
                blockingFuseIds: [
                    '1239469485',
                    '2323123233'
                ],

                // Set page targets
                pageTargets: [
                    {
                        'key': 'weather',
                        'value': ['hot', 'sunny'],
                    },
                    {
                        'key': 'age',
                        'value': '18-39',
                    },
                ]
            });
        });
    </script>
</head>

An equally valid approach is to make the same function call from inside a script.

Whichever approach is used, we recommend making the pageInit call as early as possible, because it tells Fuse what’s coming next, and offers the opportunity to make optimisations such as starting parts of the auction early.

Initialising without pageLoadComplete

If Zones are registered but fusetag.pageInit has not been called, Fuse will add them to the auction queue that is cleared in one auction once the tag has finished initialising. Any further registrations will trigger additional auctions. If the tag initialises before the components responsible for inserting Zones, each registration may trigger an individual auction.

This will function correctly and ads will display, but note that

  • Running multiple smaller auctions rather than batching is less efficient from a load-time perspective.
  • Running an independent auction for each Zone is registered may bypass configured GAM Roadblocks.

Some, but not all, Dynamic Sites allow users to navigate between pages without refreshing the browser, by replacing parts of the DOM with the content of the new page.

As with the initial load, the fusetag.pageInit function should be used to tell Fuse that a new page initialisation event has occurred, and that a new auction is required.

Page Navigation events which do not change the URL are ineligible for a refresh and will be ignored. Therefor, in the context of page navigation, the call to fusetag.pageInit should be made after window.location has been updated.

The same challenge with delayed component initialisation applies during page navigation, and for the same reason we strongly recommend the blockingFuseIds parameter be specified.

While ads will display correctly if fusetag.pageInit is not called, it solves two additional problems:

  • Signals that existing PageTargeting should be removed, and allows targeting specific to the new page to be specified
  • Signals to Fuse that the page has changed, and therefore that persistent Zones such as stickies may be refreshed

For example, the following code snippet could be executed immediately after the Web Development framework has updated the URL.

// Get an initialisation-safe reference to the Fuse Queue
const fusetag = window.fusetag || (window.fusetag = { que: [] });

fusetag.que.push(function() {
    // Tell fuse the navigation is complete, and
    // - Defer the auction until FuseIds '1239469485' and '2323123233' are registered
    // - Page targeting should be applied to the 'weather' and 'age' keys
    fusetag.pageInit({
        blockingFuseIds: [
            '1239469485',
            '2323123233'
        ],

        // Set page targets that apply to the new page.
        // This is mandatory if you use page targeting, because
        // existing page targets are removed on every page transition.
        pageTargets: [
            {
                'key': 'weather',
                'value': ['hot', 'sunny'],
            },
            {
                'key': 'age',
                'value': '18-39',
            },
        ]
    });
});

Examples