# advertisement (https://docs.salla.dev/twilight/react/api/modules/advertisement)



Use `advertisement` to read the merchant's announcement bars, the strip of text above the header. The engine already fetches them while the server renders and draws them with `PageAdvertisements` (from `@salla.sa/twilight-theme-engine/layout`), so the bar is in the first paint. Call this module yourself only when you draw the bar your own way.

```tsx title="app/components/AnnouncementBar.tsx"
import { useQuery } from '@tanstack/react-query';
import { advertisement, advertisementsFor } from '@salla.sa/twilight-theme-engine/api/advertisement';

export function AnnouncementBar({ pageSlug }: { pageSlug?: string }) {
  const { data } = useQuery({ ...advertisement.queries.list(), retry: 2 });
  const shown = advertisementsFor(data ?? [], pageSlug);

  return (
    <>
      {shown.map((ad) => (
        <p key={ad.id} style={{ backgroundColor: ad.colors?.bg, color: ad.colors?.text }}>
          {ad.description}
        </p>
      ))}
    </>
  );
}
```

## Methods [#methods]

| Method               | Parameters | Returns                    | Request                                | Login needed |
| -------------------- | ---------- | -------------------------- | -------------------------------------- | ------------ |
| `advertisement.list` | none       | `Promise<Advertisement[]>` | `GET advertisements` (timeout 3000 ms) | No           |

An `Advertisement` has `id`, and optionally `title`, `description` (the text the bar shows), `icon` (an icon class), `url`, `target`, `colors: { bg, text }` and `pages`: the page slugs it shows on, or `all`.

`list` returns every active ad, unfiltered, so one request serves every page.

## `advertisementsFor` [#advertisementsfor]

```ts
function advertisementsFor(ads: readonly Advertisement[], pageSlug: string | null | undefined): Advertisement[]
```

Returns the ads a page shows: those whose `pages` contain `all` or the page's slug (`product.single`, `cart` and so on, the `slug` of the loader's `page`). It is the rule the API applies to `?page=`, run on the full list in the browser. An ad without a `pages` array shows nowhere.

## Queries [#queries]

| Query                          | Key                                     | Options                           |
| ------------------------------ | --------------------------------------- | --------------------------------- |
| `advertisement.queries.list()` | `['advertisements', locale, { scope }]` | `staleTime: Infinity`, `retry: 0` |

The key includes the locale and the active scope, because the client sends both with the request.

## Gotchas [#gotchas]

* **Short timeout on purpose.** The root route awaits this call with the store settings on every server render, so it gets 3000 ms instead of 8000 ms. If it fails, the page still renders and the bar loads in the browser.
* **`retry: 0` in the query.** It keeps a retry from doubling the server wait. Pass your own `retry` in the browser, as the example does.
* **Empty results.** A missing or non-array `data` becomes `[]`.
* **Closed ads are yours to track.** `PageAdvertisements` hides an ad the customer closed (stored under `statusAd-<id>`) and shows no ads in the Salla mobile app. A bar you draw yourself does neither unless you add it.
* **Guests.** No token is required.

## See also [#see-also]

* [`salla-advertisement`](https://docs.salla.dev/twilight/react/web-components/salla-advertisement), the SDK component `PageAdvertisements` replaces
* [store](https://docs.salla.dev/twilight/react/api/modules/store)
* [Errors, timeouts and retries](https://docs.salla.dev/twilight/react/api/errors-timeouts-and-retries)