📊useTracking

The useTracking hooks help you measure ad visibility and interaction in your Phaser game.

The useTracking hooks monitor visibility and screen coverage of served Ads, ensuring accurate impression counting based on ReneVerse viewability standards.

---

🔭 checkAdFullVisibility()

Description: Determines whether a specific ad is fully visible in the current scene and whether it’s being blocked by any other objects.

Params

• adSprite : Phaser Sprite Object

• scene: Phaser Scene Object

import { PhaserHooks } from "@reneverse/rene-sdk-phaser";
import { IRefPhaserGame, PhaserGame } from "./game/PhaserGame";
import { useRef } from "react";

function App() {
  
  //  References to the PhaserGame component (game and scene are exposed)
  const phaserRef = useRef<IRefPhaserGame | null>(null);
  
  // Initialize PhaserHooks with API Key and Private Key for ReneVerse
  const phaserHooks = new PhaserHooks({
    apiKey: '<YOUR API KEY>',
    privateKey: '<YOUR PRIVATE KEY>',
  });
  
  const checkVisibility = async () => {
    if (phaserRef.current) {
      const scene = phaserRef.current.scene;

      if (scene) {
  
        // Fetch Ad surfaces configured in the ReneVerse portal
        const adSurfaces = await phaserHooks.useReneVerse().getAdSurfaces();
    
        // Check if there are any ad surfaces configured in the ReneVerse portal
        if (!adSurfaces.items.length) {
          console.log("No ad surfaces found");
          return;
        }
    
        // Fetch Ad from ReneVerse
        const ad = await phaserHooks
          .useReneVerse()
          .getAd(adSurfaces.items[0].adSurfaceId);
      
        // Load Ad image
        if (ad.adId) {
          scene.load.image("dynamicAd", ad.url as string);
          
          scene.load.once("complete", () => {
          
            // Get Random Position
            const x = Phaser.Math.Between(100, 900);
            const y = Phaser.Math.Between(100, 600);
          
            //  `add.sprite` is a Phaser GameObjectFactory method and it returns a Sprite Game Object instance
            const adSurface = scene.add.sprite(x, y, "dynamicAd");

            // Set display size
            adSurface.setDisplaySize(300, 200);
            
            // Check if the Ad is visible or not
            const visibilityCheck = phaserHooks
                .useTracking()
                .checkAdFullVisibility(adSurface, scene);
                
            if (visibilityCheck.isFullyVisible) {
              console.log("Ad is Fully Visible");
            } else {
              console.log("Ad is blocked");
            }
            
          };
          
          scene.load.start();
        }
      }
    }
  }
  
  // Creating a button to call the serveAd function
  return (
      <div>
        <PhaserGame ref={phaserRef} />
        <button onClick={checkVisibility}>
          Check Visibility
        </button>
      </div>
  );
}

export default App;

Returns

interface CheckAdFullVisibility {
 isFullyVisible : Boolean
 blockingSprites : [Phaser Sprite Object]
}

---

📐 calculateAdCoverage()

Description: Calculates how much of the ad is visible to the player based on the current camera view. Useful for impression tracking and engagement analysis.

Params

• adSprite : Phaser Sprite Object

• camera : Phaser Camera Object

import { IRefPhaserGame, PhaserGame } from "./game/PhaserGame";
import { useRef } from "react";

function App() {
  
  //  References to the PhaserGame component (game and scene are exposed)
  const phaserRef = useRef<IRefPhaserGame | null>(null);
  
  // Initialize PhaserHooks with API Key and Private Key for ReneVerse
  const phaserHooks = new PhaserHooks({
    apiKey: '<YOUR API KEY>',
    privateKey: '<YOUR PRIVATE KEY>',
  });
  
  const checkVisibility = async () => {
    if (phaserRef.current) {
      const scene = phaserRef.current.scene;

      if (scene) {
  
        // Fetch Ad surfaces configured in the ReneVerse portal
        const adSurfaces = await phaserHooks.useReneVerse().getAdSurfaces();
    
        // Check if there are any ad surfaces configured in the ReneVerse portal
        if (!adSurfaces.items.length) {
          console.log("No ad surfaces found");
          return;
        }
    
        // Fetch Ad from ReneVerse
        const ad = await phaserHooks
          .useReneVerse()
          .getAd(adSurfaces.items[0].adSurfaceId);
      
        // Load Ad image
        if (ad.adId) {
          scene.load.image("dynamicAd", ad.url as string);
          
          scene.load.once("complete", () => {
          
            // Get Random Position
            const x = Phaser.Math.Between(100, 900);
            const y = Phaser.Math.Between(100, 600);
          
            //  `add.sprite` is a Phaser GameObjectFactory method and it returns a Sprite Game Object instance
            const adSurface = scene.add.sprite(x, y, "dynamicAd");

            // Set display size
            adSurface.setDisplaySize(300, 200);
            
            // Check if the Ad is visible or not
            const visibilityCheck = phaserHooks
                .useTracking()
                .checkAdFullVisibility(adSurface, scene);
                
            if (visibilityCheck.isFullyVisible) {
              // if Fully visible, calculate ad coverage
              const adCoverage = phaserHooks
                .useTracking()
                .calculateAdCoverage(adSurface, scene.cameras.main);
              
              console.log(adCoverage);
            } else {
              console.log("Ad is blocked");
            }
            
          };
          
          scene.load.start();
        }
      }
    }
  }
  
  // Creating a button to call the serveAd function
  return (
      <div>
        <PhaserGame ref={phaserRef} />
        <button onClick={checkVisibility}>
          Check Visibility
        </button>
      </div>
  );
}

export default App;

Returns

interface CalculateAdCoverage {
  isVisible: Boolean
  screenCoveragePercentage: Number
  visibleArea: Number
  totalArea: Number
}