@topsort/banners-avolta

Topsort Banners - Avolta Fork

This is a custom fork of @topsort/banners with additional fallback banner backfill support for Avolta's multi-store setup.

For general usage, configuration, attributes, and API reference, see the upstream documentation.

Usage

<script
  async
  type="module"
  src="https://unpkg.com/@topsort/banners-avolta/dist/banners.mjs"
></script>
<script async type="module" src="https://unpkg.com/@topsort/analytics.js"></script>
<script>
  window.TS = {
    token: "<your topsort api key>",
    storeCode: "<your store code>",
  };
</script>

For legacy systems that don't support ES modules:

<script src="https://unpkg.com/@topsort/banners-avolta/dist/banners.iife.js"></script>

Fallback Banner Backfill

When an auction returns fewer winners than available slots, the remaining slots can be backfilled with store-specific fallback banners. This is designed for setups where multiple websites share a single slot ID (e.g., "carousel") and each website has a unique store code.

How it works

• The auction API returns a special meta-winner with isFallback: true whose asset URL points to a JSON manifest
• The library fetches the manifest and looks up fallback entries by the configured storeCode
• Remaining slots are filled with banners from the manifest

If all slots are filled by real auction winners, no fallback fetch occurs.

Configuration

Add storeCode to your window.TS configuration:

window.TS = {
  token: "<your topsort api key>",
  storeCode: "133",
};

Fallback JSON manifest format

The manifest is a JSON object keyed by store code. Each store maps to an array of fallback banner entries:

{
  "133": [
    {
      "assetURL": "https://cdn.example.com/banner-clinique.jpg",
      "assetHref": "https://example.com/brands/clinique",
      "description": "Activate Your Glow with Clinique",
      "brandName": "Clinique"
    },
    {
      "assetURL": "https://cdn.example.com/banner-la-mer.jpg",
      "assetHref": "https://example.com/brands/la-mer",
      "description": "Refresh Your Regime with La Mer",
      "brandName": "La Mer"
    }
  ],
  "52": [
    {
      "assetURL": "https://cdn.example.com/banner-offers.jpg",
      "assetHref": "https://example.com/offers",
      "description": "Special offers"
    }
  ]
}

Field	Type	Description
assetURL	string	URL of the fallback banner image
assetHref	string	Destination link for the banner
description	string (optional)	Used as the <img> alt text
brandName	string (optional)	Brand name for reference

Rendering behavior

• Fallback banners do not have a data-ts-resolved-bid attribute (no attribution tracking)
• The description field from the manifest is used as the image alt text
• Fallback banners use type: "url" with assetHref as the link destination

Graceful degradation

The fallback pipeline degrades gracefully in all failure scenarios:

• All slots filled by real winners: no manifest fetch
• No isFallback meta-winner in the response: remaining slots render nothing
• storeCode not configured: remaining slots render nothing
• Store code not found in the manifest: remaining slots render nothing
• Fetch failure or malformed JSON: remaining slots render nothing
• Fewer fallback entries than needed: fills what's available

Syncing with upstream

This fork tracks the original banners.js as upstream:

git fetch upstream
git merge upstream/main