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

1. The auction API returns a special meta-winner with isFallback: true whose asset URL points to a JSON manifest
2. The library fetches the manifest and looks up fallback entries by the configured storeCode
3. 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