Onboarding - Topsort Documentation

Übersicht

Um Offsite-Anzeigen für eine bestimmte Plattform zu starten, gewährt der Marktplatz Topsort Zugriff auf die erforderlichen Werbekonten, implementiert Offsite-Event-Tracking und Topsort übernimmt den Rest der Integration (z. B. Katalog-Sync und Offline-Events mit dem Marktplatz, Validierung). Topsort führt einen 2-wöchigen Implementierungszeitplan für jede Offsite-Plattform (z. B. Google oder Meta) durch, um einen erfolgreichen POC-Launch sicherzustellen, unterstützt durch dedizierte cross-funktionale Ressourcen des Kunden:

Engineering: ~1 Tag Aufwand eines Marktplatz-Ingenieurs (Integration und Validierung). Die Entwicklung kann wahrscheinlich in einem einzigen 90-minütigen Call mit Topsort-Ingenieuren abgeschlossen werden.
Ad Operations: ~1 Tag Marktplatz-Ad-Ops-Support für Kampagnen-Setup, QA und Launch.

Kontoarchitektur

Die automatisierte Kontobereitstellung skaliert auf Tausende von Vendors mit klarer Budgettrennung und minimalem manuellem Setup. Nachfolgend die empfohlene Kontostruktur.

Google

Marktplatz stellt bereit: Zugriff auf MCC (Manager-Konto) + MCA (Merchant Center Multi-Client-Konto)
Topsort erstellt: Vendor-Google-Ads-Konten mit erforderlicher Merchant-Center-Verknüpfung

TikTok

Marktplatz stellt bereit: Zugriff auf TikTok Business Center / Business Manager mit Berechtigung zur Verwaltung von Werbekonten und Assets
Topsort erstellt: Ein dediziertes TikTok-Werbekonto für die Topsort-Offsite-Integration, typischerweise ein Werbekonto für den Marktplatz/Händler, nicht eines pro Vendor

Snap

Marktplatz stellt bereit: Zugriff auf Snap Business Manager / Organization mit Berechtigung zur Verwaltung von Werbekonten und Billing/Assets
Topsort erstellt: Ein dediziertes Snap-Werbekonto für die Topsort-Offsite-Integration, typischerweise ein Werbekonto für den Marktplatz/Händler, nicht eines pro Vendor

Einrichtungsschritte

Kontoeinrichtung

Kontozugriff (Marktplatz)

Der Marktplatz gewährt Topsort Admin-Zugriff auf die erforderlichen Top-Level-Werbeplattform-Konten für die Kanäle, die onboarded werden. Siehe Kontoarchitektur oben für die spezifischen Konten, auf die pro Plattform Zugriff gewährt werden soll.

Kontoerstellung (Topsort)

Topsort provisioniert die Vendor-Level-Kontostruktur unter diesen Marktplatz-Containern, einschließlich Child-Werbekonten, Business Managern oder Merchant-Center-Konten, die für die Integration benötigt werden. Siehe Kontoarchitektur oben für das, was Topsort auf jeder Plattform erstellt. Der Marktplatz kann Topsort eine Liste der für Offsite zu aktivierenden Vendors bereitstellen.

Katalog-Sync (Topsort)

Wenn katalogbasierte Offsite-Formate im Scope sind, synchronisiert Topsort den Marktplatz-Katalog mit der Offsite-Plattform und mappt die Produkte jedes Vendors in die entsprechende Plattform-Kontostruktur für diesen Vendor.

Event-Tracking-Einrichtung (Marktplatz)

Der einzige Bereich, in dem der Marktplatz Entwicklung betreiben muss, ist Event-Tracking. Um Offsite-Events zu melden, verwenden Sie denselben /v2/events-Endpoint wie für Onsite-Events und übergeben zusätzliche Parameter im Request-Body.

Opake User-ID

Dieselbe opaqueUserId, die für Onsite-Events verwendet wird, sollte auch für Offsite-Attribution wiederverwendet werden. Keine separate Offsite-Kennung erforderlich. Topsort benötigt eine persistente, datenschutzfreundliche User-Kennung, um Klicks und Käufe kanalübergreifend zu verbinden. Dieselben Onsite-Anforderungen gelten für Offsite-Nutzung:

Persistenz: Sollte für das Attributionsfenster stabil bleiben (typischerweise 7–30 Tage).
Konsistenz: Derselbe User sollte bei Besuchen und Kanälen nach Möglichkeit dieselbe ID erhalten.
Datenschutzfreundlich: Darf keine PII wie E-Mail, Telefonnummer oder Name enthalten.

Klick-URL

Die URL, die der User hat, wenn er über einen Offsite-Ad-Klick auf Ihrer Site landet, enthält wichtige Query-Parameter. Beispiel-Klick-URL:

https://www.retailer.com/search?q=shampoo&
externalCampaignId=9d2d7d7d-5d4f-4d8e-a8d0-2d7a6f9c1234&
externalVendorId=vendor_abc123&
gclid=CjwKCAj_example123&
utm_source=google&
utm_medium=c

Query-Parameter:

gclid — von Google angehängte Klick-ID
externalCampaignId und externalVendorId — Query-Parameter mit Topsort-Kampagnen-ID und Vendor-ID, von Topsort angehängt. Sollen zusammen mit dem User-Attributionsstatus mindestens für die Dauer des Attributionsfensters (konfigurierbar 7–30 Tage) persistieren. Sollen Navigation und wiederholte Besuche überdauern, damit nachfolgende Kauf-Events korrekt mit dem auslösenden Offsite-Ad-Klick verknüpft werden können.

Klicks melden

Senden Sie das folgende Event, wenn ein User über einen Offsite-Ad-Klick auf Ihrer Site landet. Alle Felder sind erforderlich.

POST /v2/events

{
  "clicks": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "entity": {
        "id": "product1",
        "type": "product"
      },
      "externalCampaignId": "<Topsort UUID>",
      "externalVendorId": "<Topsort externalVendorId>",
      "dsp_metadata": {
        "gclid": "<Google click ID>"
      },
      "channel": "offsite"
    }
  ]
}

Käufe melden

Alle Felder sind erforderlich.

POST /v2/events

{
  "purchases": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "items": [
        {
          "productId": "product1",
          "vendorId": "<externalVendorId>",
          "unitPrice": 75.0,
          "quantity": 1
        },
        {
          "productId": "product2",
          "vendorId": "<externalVendorId>",
          "unitPrice": 25.0,
          "quantity": 1
        }
      ]
    }
  ]
}

Events mit Offsite-Plattformen teilen

Der Kunde muss Conversion-Events nicht separat an die Offsite-Plattform melden. Topsort sendet automatisch berechtigte Kauf-Events, die mit der entsprechenden Klick-ID (z. B. Google Click ID oder GCLID) verknüpft sind, über die Offline-Conversions-API der Plattform.

Onboarding-Zeitplan

Woche 1 – Zugriff und Event-Tracking-Setup

Zugriff auf erforderliche Konten gewähren
Event-Tracking-Implementierung starten
Katalog bei Bedarf mit Offsite-Plattform synchronisieren
Erste Systemkonfiguration beginnen

Woche 2 – Integration und Daten-Setup

Integration abschließen und Tests beginnen
Event-Tracking und Katalogstruktur/-qualität validieren
Nach Abschluss des Setups mit Live-Kampagne validieren und Performance überwachen

Documentation Index

​Übersicht

​Kontoarchitektur

​Google

​Meta

​TikTok

​Snap

​Einrichtungsschritte

​Kontoeinrichtung

​Kontozugriff (Marktplatz)

​Kontoerstellung (Topsort)

​Katalog-Sync (Topsort)

​Event-Tracking-Einrichtung (Marktplatz)

​Opake User-ID

​Klick-URL

​Klicks melden

​Käufe melden

​Events mit Offsite-Plattformen teilen

​Onboarding-Zeitplan

​Woche 1 – Zugriff und Event-Tracking-Setup

​Woche 2 – Integration und Daten-Setup