@overlayed/ads

The methods available on the ads package

The @overlayed/ads package provides methods for managing ads within your overlay application.

init

Initialize the ads system.

• Type

  init(): void;
  

• Details

  Call this method when your HTML/JS first loads. This function can be called multiple times safely - it will only execute once.

• Example

  import overlayedAds from "@overlayed/ads";
  
  overlayedAds.init();
  

setAdsEnabled

Control the visibility of ads throughout your application.

• Type

  setAdsEnabled(enabled: boolean): void;
  

• Details

  This method allows you to enable or disable ads globally. This can be useful for paid users or specific application states. Note that it’s recommended to omit the RevIQ ads script entirely on pages where ads are not desired.

• Example

  import overlayedAds from "@overlayed/ads";
  
  // Disable ads for premium users
  overlayedAds.setAdsEnabled(false);
  
  // Re-enable ads
  overlayedAds.setAdsEnabled(true);
  

setKv

Set a single key-value pair for ad targeting.

• Type

  setKv(key: string, value: string): void;
  

• Details

  Track key values that can later be used to filter ad metrics. These values help with ad targeting and performance analysis.

  Warning: You may not pass any user-identifiable data (including names, addresses, or user IDs) in targeting.

• Example

  import overlayedAds from "@overlayed/ads";
  
  overlayedAds.setKv("page_id", "HomePage");
  overlayedAds.setKv("game_mode", "competitive");
  

setKvs

Set multiple key-value pairs for ad targeting at once.

• Type

  setKvs(keyValues: Record<string, string>): void;
  

• Details

  Convenience method for setting multiple key values simultaneously. Same restrictions apply as setKv - no user-identifiable data allowed.

• Example

  import overlayedAds from "@overlayed/ads";
  
  overlayedAds.setKvs({
  	page_id: "HomePage",
  	game_mode: "competitive",
  	user_level: "gold",
  });
  

setUid

Provide user identifiers to improve ad performance.

• Type

  setUid(uid: { e?: string; u?: string; p?: string }): void;
  

• Details

  Providing a UID significantly improves ad performance and is highly recommended, though optional. The system complies with all privacy regulations and does not store user-identifiable data. Once passed to RevIQ, the UID is normalized and hashed - the original value is never stored.

  If the user has opted out of tracking, the UID will not be stored or transmitted, making it safe to call regardless of tracking preferences.

  • e: Email address
  • u: Username
  • p: Phone number

• Example

  import overlayedAds from "@overlayed/ads";
  
  // With email
  overlayedAds.setUid({ e: "[e-mail]" });
  
  // With username
  overlayedAds.setUid({ u: "BestGamerX" });
  
  // With phone
  overlayedAds.setUid({ p: "[phone]" });
  

showConsent

Display the consent dialog to users.

• Type

  showConsent(): void;
  

• Details

  Shows a consent dialog for ad tracking. This is typically shown automatically to users as needed, but can be manually triggered if required.

• Example

  import overlayedAds from "@overlayed/ads";
  
  // Show consent dialog when user clicks privacy settings
  overlayedAds.showConsent();
  

registerWindow (Electron Main Process)

Register a BrowserWindow or RenderWindow for ad support.

• Type

  overlayed.ads.registerWindow(browserWindow: BrowserWindow): void;
  

• Details

  Call this method for any BrowserWindow or RenderWindow where you intend to show ads. This method:

  • Sets up a link handler to open ads safely and block malicious behavior
  • Sets the user agent for all requests, removing non-standard portions that may trigger IVT (invalid traffic)

• Example

  import { overlayed } from "@overlayed/app";
  
  const window = new BrowserWindow({
  	// window options
  });
  
  // Register the window for ads
  overlayed.ads.registerWindow(window);