Skip to main content
Submit a request

Google Rewarded Ads: Publisher Integration Guide

Updated

This document provides instructions for implementing Google Rewarded Ads on your site. The implementation requires adding code to your site's <head> and using event listeners to manage the ad lifecycle. Freestar will handle all necessary GAM (Google Ad Manager) configuration.

1. Head code implementation

Place the following code block within the <head> section of your website, directly below the freestar.config.enabled_slots = []; line in your existing Freestar configuration.

Ad unit path

You must replace the placeholder adUnitPath value with the unique ad unit path provided by your Freestar Point of Contact.

Triggering the ad

The DOMContentLoaded listener in the code below is an example of how to show the ad when a user clicks an element. You must modify this logic to match your site's implementation. Specifically, update the getElementById('rewardedAdTrigger') code to target the unique ID of the HTML element (e.g., a button) that will trigger the ad.

// Freestar Rewarded Ad Configuration
var rewardedAdReadyEvent; // Stores the rewarded ad ready event
var adUnitPath = '/YOUR_UNIQUE_AD_UNIT_PATH'; // Replace with the path from Freestar

// EXAMPLE: Attach event listener to the ad trigger element.
// IMPORTANT: You must modify this to target your specific trigger element.
document.addEventListener('DOMContentLoaded', () => {
  // Change 'rewardedAdTrigger' to the ID of your trigger element.
  const rewardedAdTrigger = document.getElementById('rewardedAdTrigger'); 
  if (rewardedAdTrigger) {
    rewardedAdTrigger.addEventListener('click', () => {
      if (rewardedAdReadyEvent) {
        rewardedAdReadyEvent.makeRewardedVisible(); // Displays the ad
      } else {
        console.warn('Rewarded ad is not ready to be shown yet.');
      }
    });
  } else {
    console.error('Rewarded ad trigger element not found. Cannot attach click listener.');
  }
});

// Add event listeners for rewarded ad lifecycle
freestar.queue.push(() => {
  // REQUIRED: The rewarded ad cannot be shown until the rewardedSlotReady event fires
  googletag.pubads().addEventListener('rewardedSlotReady', (event) => {
    console.log(`[Freestar] The ad ${adUnitPath} is ready!`);
    rewardedAdReadyEvent = event; // Store the event for later display
    // PUBLISHER: Add custom logic here (e.g., enabling the trigger button)
  });

  // OPTIONAL: Fires when the user has earned the reward by completing the ad.
  googletag.pubads().addEventListener('rewardedSlotGranted', (event) => {
    console.log(`[Freestar] Reward granted: ${event.payload.amount} ${event.payload.type}.`);
    // PUBLISHER: Add custom logic here to grant the user their reward
  });

  // OPTIONAL: Fires when the user closes the ad, after the ad is granted or abandoned.
  googletag.pubads().addEventListener('rewardedSlotClosed', (event) => {
    console.log(`[Freestar] The user closed ${adUnitPath}.`);
    // PUBLISHER: Add custom logic here (e.g., UI cleanup)
  });
});

2. Using the event listeners

The provided code includes three key event listeners to control the rewarded ad experience. You can add your custom logic within these listeners.

  • rewardedSlotReady (Required)

    This event fires after the rewarded ad has been successfully fetched and is ready for display. The ad cannot be shown until this event has fired. Use this listener to enable the UI element (e.g., a button) that the user clicks to watch the ad.

  • rewardedSlotGranted (Optional)

    This event fires once the user has successfully met the criteria to earn the reward (e.g., watched the entire video). You can use this listener to trigger the logic that delivers the promised reward. The event.payload object contains the reward amount and type configured in GAM.

  • rewardedSlotClosed (Optional)

    This event fires whenever the user closes the ad creative, regardless of whether they earned the reward or not, which is helpful for any necessary UI cleanup after the ad experience is finished.

3. Final step: Freestar QA

Once you have implemented the head code on your site, please notify your Freestar Point of Contact. Our team will perform a quality assurance check to ensure the implementation is working correctly before the feature goes live. Please detail any custom events or triggers you've enabled as part of this implementation. Knowing how to trigger the rewarded ad will make testing much easier.

Related articles