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: "bestgamerx@gmail.com" });

// With username
overlayedAds.setUid({ u: "BestGamerX" });

// With phone
overlayedAds.setUid({ p: "+1234567890" });

​
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);