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.

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>
      ))}
    </>
  );
}

MethodsCopy Anchor Link

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.

advertisementsForCopy Anchor Link

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.

QueriesCopy Anchor Link

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

GotchasCopy Anchor Link

• 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 alsoCopy Anchor Link

• salla-advertisement, the SDK component PageAdvertisements replaces
• store
• Errors, timeouts and retries