> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overlayed.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Overlay Ads

> Ads allow you to monetize your overlay, this guide will cover various utilities we provide for managing them.

## Before You Begin

Before you start setting up ads, make sure to contact the Overlayed team to discuss ads on your app. We'll discuss ad
positioning, ad units, and more. It's crucial to start this process early so that we have time to setup the ads before
you start using them.

## Installation

To start with ads, you'll need to install the `@overlayed/ads` package:

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm i @overlayed/ads
  ```

  ```bash npm theme={null}
  npm i @overlayed/ads
  ```

  ```bash yarn theme={null}
  yarn add @overlayed/ads
  ```
</CodeGroup>

## Setup

### Electron

On the electron side, for any BrowserWindow or RenderWindow you create and intend to show ads in, you'll need to call:

```ts theme={null}
overlayed.ads.registerWindow(browserWindow);
```

### Preload

Within your electron app's [preload script](https://www.electronjs.org/docs/latest/tutorial/tutorial-preload), you'll
need to add the following import:

```ts theme={null}
import "@overlayed/app/preload";
```

This will automatically execute code that facilitates Overlayed's communication between the electron process and
rendering process.

### Render Process

Within the render process, there are a few more things to set up:

#### Initialization

Call the `init` method when your HTML/JS first loads:

```ts theme={null}
import overlayedAds from "@overlayed/ads";

overlayedAds.init();
```

You can call this function as many times as you want, it will only execute once.

#### Adding the ads script

Use the package helpers to build and mount the script with the correct app domain:

```ts theme={null}
import { getAdsScriptElement } from "@overlayed/ads";

const script = getAdsScriptElement({
	onError: (event) => {
		// Add your logging/observability here
		console.error("Failed to load ads script", event);
	},
});

if (script) {
	document.head.appendChild(script);
}
```

If you need the script URL directly, use `getAdsScriptUrl()` from `@overlayed/ads`.

## Conclusion

That concludes the required setup for ads. Check out the [configuration](/ads/configuration) guide for more information
on how to configure ad units, conditionally disable ads, and more.