> ## 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 Configuration

> Learn how to configure targeting and refresh ads at runtime.

## Refreshing Ads

Use `refreshAdsViaDivMappings` to request ad fills for specific placements on your page. Call it on initial mount and
again whenever the page context changes (for example, on route navigation).

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

overlayedAds.refreshAdsViaDivMappings([
	{
		divId: "right-rail-2",
		baseDivId: ".htlad-medrec",
		targeting: { page_id: "HomePage" },
	},
	{
		divId: "right-rail-3",
		baseDivId: ".htlad-medrec",
	},
]);
```

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

Each mapping describes one ad slot:

* `divId` — the `id` of the DOM element where the ad renders.
* `baseDivId` — the base selector for the ad unit (for example, `.htlad-medrec`). Overlayed works with you to pre-approve
  the set of base selectors your app uses.
* `targeting` — optional per-slot key-value targeting merged with page-level targeting.

## Page-Level Targeting

For targeting that applies to every subsequent ad request, use `setPageTargeting`:

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

setPageTargeting({ page_id: "HomePage" });
```

`init()` automatically sets `app_id` page targeting for you.

## Conditionally Disabling Ads

There is no runtime method to toggle ads on and off. To hide ads for a user (for example, a paid subscriber), do not
mount the ads script for that user and do not render the ad containers in your UI. See the
[setup guide](/ads/introduction#adding-the-ads-script) for how to conditionally mount the script.