Hosted Script Passback

The passback script is executed client-side and only injected into the DOM if a failure condition is detected.

How It Works

• Define a Passback URL Provide a publicly hosted HTTPS URL pointing to a JavaScript file. This script will be executed if the primary ad request fails or returns no content.

• Automatic Script Injection If a failure is detected, the render library dynamically injects the passback script into the page, appending a targetId query parameter corresponding to the ad container's DOM ID.

• Execution Context The script is executed in the context of the ad slot and should be responsible for rendering fallback content within the provided targetId.

• Publisher Responsibility Publishers must ensure the script is:

  • Hosted over HTTPS

  • Self-contained (no external dependencies unless bundled)

  • Implemented to handle DOM injection using the targetId parameter

Enabling Passback

To activate the passback feature, configure your tag with a passback option specifying the script URL. You may also enable passbackTest mode for development.

var options = {
	passback: '/passback.js', // URL of the passback script
	passbackTest: 1, // Enable passback testing
};

Example: Simple House Ad Fallback

The following example script identifies the target container and injects a simple styled fallback banner:

// Get the current script and extract the "targetId" from its query parameters
const  script = document.currentScript;
const  targetId = new  URL(script.src).searchParams.get('targetId');

if (targetId) {

	// Find the target element on the page by its ID
	const  targetElement = document.getElementById(targetId);

	// Create a basic banner
	const  banner = document.createElement('div');

	banner.style = `
	width: 100%;
	height: 250px;
	background-color: #f4f4f4;
	border: 2px solid #ccc;
	display: flex;
	justify-content: center;
	align-items: center;
	font-family: Arial, sans-serif;
	color: #333;
	font-size: 18px;
	font-weight: bold;
	text-align: center;
	`;
	banner.innerText = 'Passback House Banner';

	// Add the banner to the target element
	targetElement.appendChild(banner);
}

Testing the Passback Feature

To verify that the passback logic is working correctly, you can enable passback testing mode within the render library’s configuration. This forces a simulated no-fill condition and triggers the passback flow, even if an ad would normally be served.

What to Expect

When test mode is active or a genuine no-fill occurs, you should observe the following in the browser:

1. Injected Script Tag

An additional <script> tag will appear in the DOM, dynamically inserted by the render library:

<script src="https://cdn.example.com/passback.js?targetId=ad-slot-1"></script>

2. Passback Content Rendered

Depending on your script’s logic, you should see fallback content rendered inside the target container. For example:

<div id="ad-slot-1"> <div style="width:100%; height:250px; background:#f4f4f4; ..."> Passback House Banner </div> </div>