> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sponsored Brands Auktionsanfragen und -antworten

Sponsored Brands Auktionen funktionieren, indem Auktionsanfragen mit
Platzierungsdetails und Targeting-Triggern gesendet werden und dann strukturierte Antworten mit
gewinnenden Kampagnen mit allen notwendigen kreativen Elementen und Metadaten empfangen werden.

## Verfügbare Vorlagen

Sponsored Brands Kampagnen werden mit einer der drei vorgefertigten Vorlagen erstellt:

* **Produktkollektion**: Mehrere Produkte auf einer Zielseite angezeigt für umfassende Produktentdeckung
* **Produkt-Spotlight**: Ein einzelnes Produkt und ein Kreativinhalt
* **Store-Schaufenster**: Leitet Traffic direkt zur Seite eines Verkäufer-Stores für Markenbewusstsein

## Auktionsanfrage

Auktionsanfragen für Sponsored Brands folgen dem Standard-Auktionsformat mit
spezifischen Triggern für Targeting und Unterstützung für standortbasiertes Filtern:

```json theme={null}
{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "products": {
          "ids": ["pmk_1", "pmk_8"]
        },
        "category": {
          "id": "electronics"
        },
        "searchQuery": "cool electronics"
      },
      "geoTargeting": "santiago",
      "opaqueUserId": "user-123"
    }
  ]
}
```

### Anfrageparameter

* **winners**: Anzahl der zurückzugebenden Sponsored Brands Kampagnen
* **placementId**: Bezeichner für die Sponsored Brands Platzierung
* **triggers**: Targeting-Kriterien unter Verwendung eines der folgenden:
  * **products.ids**: Array spezifischer Produkt-IDs zum Targeting
  * **category.id**: Produktkategorie für breiteres Targeting
  * **searchQuery**: Suchbegriffe für keyword-basiertes Targeting
* **geoTargeting**: Geografischer Standortbezeichner für standortbasiertes Kampagnenfiltern
* **opaqueUserId**: Anonymisierte Benutzer-ID für Personalisierung und erweitertes Targeting

### Geo-Targeting-Filterverhalten

Das Auktionssystem filtert automatisch Kampagnen basierend auf Geo-Targeting:

* **Standortübereinstimmung**: Kampagnen mit spezifischen Geo-Targeting-Einstellungen nehmen nur teil, wenn das `geoTargeting`-Feld mit ihren konfigurierten Standorten übereinstimmt
* **Kein Geo-Targeting**: Kampagnen ohne Geo-Targeting-Einschränkungen nehmen unabhängig vom `geoTargeting`-Wert an allen Auktionen teil
* **Mehrere Standorte**: Kampagnen, die mehrere Standorte anvisieren, nehmen teil, wenn die Anfrage mit einem ihrer konfigurierten Standorte übereinstimmt
* **Rückwärtskompatibilität**: Bestehende Kampagnen ohne Geo-Targeting funktionieren weiterhin wie zuvor

## Auktionsantwort

Die Auktionsantwort gibt gewinnende Sponsored Brands Kampagnen mit vollständigen
kreativen Elementen und Metadaten zurück:

```json theme={null}
{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "resolvedBidId": "ChAGc-G66Wt7LKQEOcW8VBdIEhABjz_zDXx7db-ZYpxiwJ3DGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATEQATDrrg8",
          "productId": "pmk_1",
          "type": "url",
          "id": "www.topsort.com",
          "vendorId": "vendor_id",
          "content": {
            "headline": "Campaign Headline",
            "logo": "https://some.url.com/logo.jpeg"
          },
          "campaignId": "018f3ff3-0d7c-7b75-bf99-629c62c09dc3",
          "productIds": ["pmk_1", "pmk_4", "pmk_8"]
        }
      ],
      "error": false
    }
  ]
}
```

### Antwortfelder

#### Winner-Objekt

* **rank**: Positionsrang der gewinnenden Kampagne
* **resolvedBidId**: Eindeutige ID für Auktionsverfolgung und Zuordnung
* **productId**: Hauptprodukt-ID für die Kampagne
* **type**: Kampagnentyp (immer "product" für Sponsored Brands)
* **id**: Kampagnen-ID
* **title**: Kampagnentitel für Anzeigezwecke
* **campaignId**: UUID der Sponsored Brands Kampagne
* **productIds**: Array aller in der Kampagne enthaltenen Produkte (1-5 Produkte)

#### Assets-Array

Kreative Elemente für das Rendering der Sponsored Brands Anzeige:

* **url**: CDN-URL für das Asset
* **role**: Asset-Typ ("image" für kreatives Banner, "logo" für Markenlogo)
* **contentType**: MIME-Typ des Assets
* **contentLength**: Dateigröße in Bytes
* **width/height**: Asset-Dimensionen in Pixeln

#### Content-Objekt

Kampagneninhalt für Rendering:

* **headline**: Kampagnenüberschriftentext
* **brandName**: Marken- oder Verkäufername
* **creative1**: Zusätzliche kreative Asset-URL (Videos, sekundäre Bilder)

## Implementierungshinweise

### Rendering-Flexibilität

Kreative Assets, Überschrift und productIds werden separat in der
Auktionsantwort zurückgegeben, sodass Sie diese Elemente entsprechend Ihren
Frontend-Design-Anforderungen rendern können. Das Assets-Array enthält alle notwendigen kreativen Komponenten
mit klarer Rollenidentifikation.

### Multi-Produkt-Unterstützung

Sponsored Brands Kampagnen können 1-5 Produkte gleichzeitig bewerben. Das
`productIds`-Array enthält alle in der Kampagne enthaltenen Produkte, während
`productId` das Hauptprodukt für Tracking-Zwecke darstellt.

### Vorlagenintegration

Obwohl Kampagnen mit den verfügbaren Vorlagen erstellt werden (Produktkollektion,
Produkt-Spotlight, Store-Schaufenster), liefert die Auktionsantwort alle
notwendigen Assets und Inhalte unabhängig von der verwendeten Vorlage und gewährleistet
konsistente Integration über alle Kampagnentypen hinweg.

### Inhaltsspezifikationen

Alle kreativen Assets (Bilder und Videos), die für Sponsored Brands Kampagnen hochgeladen werden,
müssen diese Anforderungen erfüllen:

* **Unterstützte Formate**: JPEG, PNG, WEBP, GIF, MP4
* **Maximale Dateigröße**: 5 MB pro Kreativinhalt/Video

***

**Zuletzt aktualisiert:** 
<time dateTime="2025-11-18">2025-11-18</time>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.