Third Party Demand - Topsort Documentation

Vue d’ensemble

Topsort offre deux moyens d’intégrer la demande tierce dans votre stack publicitaire :

Médiation de la demande – Pour les listings sponsorisés, transmettez des offres provenant de sources de demande externes (p. ex., Criteo) dans l’enchère Topsort, où elles concurrencent directement la demande Topsort. L’offre la plus élevée l’emporte, quelle que soit la source.
Demand Fallback – Pour les emplacements de bannières, Topsort peut retourner un tag Google Ad Manager (GAM) lorsqu’aucune demande Topsort n’est disponible, permettant à la marketplace de générer des revenus supplémentaires via la publicité programmatique.

Médiation de la demande

Qu’est-ce que la médiation de la demande ?

Auparavant, les enchères Topsort ne recevaient de la demande que de sources Topsort (soit de vendeurs au sein d’une marketplace, soit via Toppie). Avec la médiation de la demande, Topsort peut désormais récupérer de la demande auprès de sources tierces.

La première source de demande tierce intégrée est Criteo, une plateforme publicitaire de retail media de premier plan avec des budgets provenant des grandes marques du monde entier. Pour chaque emplacement de listing sponsorisé, un détaillant récupère les offres de Criteo et les transmet à Topsort. Topsort compare les offres Criteo avec ses propres offres et sélectionne les offres gagnantes parmi elles.

Topsort peut facilement accueillir d’autres sources de demande au-delà de Criteo, à condition que leurs offres puissent être envoyées via le paramètre demandSources de l’endpoint d’enchère.

Fonctionnement de la facturation

Avec la médiation de la demande utilisant Criteo :

Le détaillant est propriétaire du compte/de l’instance Criteo, pas Topsort
Les annonceurs paient Criteo directement
Criteo facture les annonceurs, prélève ses frais de plateforme et reverse au détaillant sa part de revenus
Topsort facture le détaillant séparément (structure de facturation à définir)

Avantages

Les détaillants peuvent générer des revenus publicitaires supplémentaires grâce à la médiation de la demande :

Combler les lacunes : Lorsqu’il n’y a pas de demande Topsort pour les requêtes publicitaires, la demande Criteo peut être disponible
Accroître la concurrence : Lorsque la demande Topsort existe, la demande Criteo peut enchérir plus haut, augmentant ainsi les revenus globaux

À qui est-ce destiné ?

Bien que n’importe quel client puisse ajouter la demande Criteo, cette intégration est particulièrement pertinente pour les clients susceptibles d’attirer des dépenses publicitaires Criteo significatives :

Grandes marketplaces américaines : De nombreuses grandes marques américaines enchérissent sur des publicités retail media via des outils comme Pacvue et Skai, qui enchérissent à leur tour sur l’inventaire Criteo. Cette configuration permet aux grandes marques d’éviter une intégration directe avec chaque détaillant sur lequel elles souhaitent faire de la publicité.
Grandes marketplaces LATAM : Criteo a une présence significative en Amérique latine, ce qui rend cette intégration précieuse pour les grandes marketplaces LATAM également.

Processus d’intégration

Pour intégrer une marketplace avec la médiation de la demande :

Configurer les emplacements dans Criteo

La marketplace doit configurer dans son compte Criteo tous les emplacements pour lesquels elle souhaite intégrer la demande Criteo.

Mettre à jour le code frontend

Au chargement de la page, la marketplace doit :

Récupérer les offres de Criteo pour l’emplacement
Envoyer ces offres à Topsort en tant que paramètre supplémentaire dans la requête d’enchère

Traiter la réponse de l'enchère

Topsort retourne les offres gagnantes, qui peuvent inclure aussi bien des gagnants Topsort que Criteo.

Signaler les événements

Si des gagnants Criteo sont présents, la marketplace doit signaler les événements à la fois à Topsort et à Criteo.

Implémentation API

L’endpoint d’enchères a été étendu pour prendre en charge les sources de demande externes. L’ajout d’une demande externe nécessite un nouveau champ d’entrée et deux nouveaux champs de réponse pour les gagnants de l’enchère.

Le nombre d’offres externes est limité à 100 par requête d’enchère.

Modifications de la requête

Un nouveau champ demandSources a été ajouté à l’objet d’enchères :

demandSources: Tableau d’objets demandSource
- source: Enum identifiant la source de demande externe (ex. : "criteo")
- bids: Tableau d’objets Bid, un pour chaque offre externe

Chaque objet Bid contient :

chargeType: Enum (seul "CPC" est pris en charge dans la première version)
entity: Objet avec les champs type et id identifiant le produit sponsorisé
bidAmount: Montant de l’offre dans la devise de la marketplace
metadata: Champ libre pour toutes les métadonnées nécessaires dans la réponse gagnante (ex. : URLs de balise)

Modifications de la réponse

L’objet Winner a été mis à jour avec :

demandSource: Chaîne identifiant la source de l’offre gagnante (ex. : "topsort" ou "criteo"). N’apparaît que lorsque des offres externes sont incluses dans la requête.
metadata: Pour les gagnants d’offres externes, transmet les métadonnées d’entrée de l’offre externe. Omis pour les offres internes/Topsort.

Pour les offres externes, le champ campaignId sera omis de l’objet gagnant.

Cas d’erreur

Nouveaux cas d’erreur spécifiques à la médiation de la demande :

La demande externe n’est pas autorisée pour la marketplace
Offres externes invalides (entités non-produit, type de charge incorrect ou montant d’offre négatif)
Trop d’offres externes (plus de 100)
Demande externe avec un type d’annonce autre que les listings
Source de demande externe invalide (seul Criteo est actuellement pris en charge)

Exemple de requête

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "paper"
      },
      "opaqueUserId": "user123",
      "demandSources": [
        {
          "source": "criteo",
          "bids": [
            {
              "chargeType": "CPC",
              "entity": {
                "type": "product",
                "id": "product123"
              },
              "bidAmount": 0.75,
              "metadata": {
                "beaconUrls": ["https://example.com/beacon"],
                "clickUrls": ["https://example.com/click"]
              }
            }
          ]
        }
      ]
    }
  ]
}

Exemple de réponse

{
  "results": [
    {
      "resultType": "listings",
      "winners": [
        {
          "demandSource": "criteo",
          "type": "product",
          "id": "product123",
          "resolvedBidId": "UkoVYQoQBpaVc2jmdMO0BA4QS9VdHRIQAZgtj1MxeFGT5HL2fhBhKRoQBlhiMAUTfKyPJHhKpsqrQCIKCgZzdWJ3YXkQATCmFUDTBEgBUMXa8pu8Mw",
          "rank": 1,
          "metadata": {
            "beaconUrls": ["https://example.com/beacon"],
            "clickUrls": ["https://example.com/click"]
          }
        },
        {
          "demandSource": "topsort",
          "campaignId": "01982d6e-8655-70e2-94e3-3e5e764b4753",
          "type": "product",
          "id": "product456",
          "resolvedBidId": "zOzJwgoQBpaVfNrgdmeSBLgWZwYYmhIQAZgtboZVcOKU4z5edktHUxoQBlhiMAUTfKyPJHhKpsqrQCIQCgxwYW5lcmEtYnJlYWQQATCmFUDTBEgBUKH3-5u8Mw",
          "rank": 2
        }
      ],
      "error": false
    }
  ]
}

Pour plus d’informations sur l’API d’enchères, consultez laréférence API Create Auctions

Demand Fallback

Qu’est-ce que l’intégration GAM Fallback ?

Pour les clients configurés pour cette intégration, l’endpoint d’enchères Topsort retourne dans sa réponse un tag Google Ad Manager (GAM) — quelques lignes de code — pour les emplacements de bannières activés pour la demande GAM, chaque fois qu’il n’y a pas de demande Topsort pour une requête publicitaire sur ces emplacements.

Le détaillant affiche le tag GAM, qui présente une bannière publicitaire GAM, générant ainsi des revenus supplémentaires à partir d’un inventaire qui resterait autrement invendu.

Diagramme du flux GAM fallback montrant l'enchère retournant un tag GAM en l'absence de demande Topsort

Avantages

Monétiser l’inventaire invendu : Les marketplaces peuvent générer des revenus avec les emplacements de bannières même en l’absence de demande Topsort
Sources de demande flexibles : Topsort peut configurer les placements GAM pour récupérer de la demande provenant soit d’enchères ouvertes (annonceurs non endémiques redirigeant vers d’autres sites web), soit d’accords directs

À qui est-ce destiné ?

Tout client pouvant obtenir de la demande GAM via les enchères ouvertes GAM est éligible à cette intégration.

C’est idéal pour les marketplaces avec un inventaire de bannières invendu ou à faible demande dans Topsort.

Processus d’intégration

Si votre marketplace est intéressée par le GAM fallback, contactez votre équipe de compte Topsort. Nous travaillerons ensuite avec vous pour établir un calendrier d’intégration.

L’intégration typique prend 3 à 4 semaines et suit ces étapes :

Aligner le périmètre du pilote

Sélectionnez 2 à 3 emplacements de bannières et convenez des politiques de modération de contenu.

Configurer la connexion GAM MCM

Reliez les comptes Topsort et détaillant, et mettez à jour ads.txt et sellers.json. Topsort utilise le Multiple Customer Management (MCM) de GAM, qui permet au compte GAM de Topsort de contrôler d’autres comptes (p. ex., les comptes détaillants).

Configurer le registre partagé des emplacements

Assurez-vous que les identifiants d’unités publicitaires, les dimensions et les placements correspondent entre Topsort et GAM.

Implémenter le flux de passback

Topsort appliquera les paramètres dans l’interface GAM et générera des tags de passback GPT (extraits de code JavaScript). Topsort mettra à jour sa configuration pour retourner des tags GAM pour toute enchère de bannière sans demande Topsort. Le détaillant mettra à jour la logique frontend pour afficher un tag de passback si l’enchère Topsort en retourne un.

Tests

Topsort validera l’intégration via des emplacements de test contrôlés.

Mise en production

Une fois les tests terminés, l’intégration est mise en production sur les emplacements convenus.

Exemple de requête

Lorsqu’aucune demande Topsort n’est disponible pour un emplacement de bannière activé pour le fallback GAM, l’ endpoint d’enchères retourne un snippet GAM dans le champ asset du gagnant. Le détaillant affiche ce snippet pour présenter une bannière publicitaire GAM.

{
  "auctions": [
    {
      "type": "banners",
      "slots": 1,
      "slotId": "fake-slot-2",
      "products": {
        "ids": ["prod-a1b2c3d4"]
      }
    }
  ]
}

Exemple de réponse

{
  "results": [
    {
      "resultType": "banners",
      "winners": [
        {
          "asset": [
            {
              "content": "{\"type\": \"gam_snippet\", \"content\": \"<div id=\\\"gam-ad\\\"><script>googletag.cmd.push(function() { googletag.display(\\\"div-gpt-ad-12345\\\"); });</script></div>\"}"
            }
          ],
          "type": "url",
          "id": "https://www.example.com",
          "resolvedBidId": "PHRSCwoQBpvFL1sveOSZBCyVii_LCRIQAAAAAAAAAAAAAAAAAAAAABoQAAAAAAAAAAAAAAAAAAAAACIbChdodHRwczovL3d3dy5leGFtcGxlLmNvbRAFUIDQzO7O7_H__wFyEAAAAAAAAAAAAAAAAAAAAAA",
          "rank": 1
        }
      ],
      "error": false
    }
  ]
}

Chaque entrée dans le tableau asset contient un champ content avec une chaîne JSON de type gam_snippet. Le détaillant doit analyser ce contenu et afficher le HTML/JavaScript intégré pour présenter la bannière GAM.

Documentation

​Vue d’ensemble

​Médiation de la demande

​Qu’est-ce que la médiation de la demande ?

​Fonctionnement de la facturation

​Avantages

​À qui est-ce destiné ?

​Processus d’intégration

​Implémentation API

​Modifications de la requête

​Modifications de la réponse

​Cas d’erreur

​Exemple de requête

​Exemple de réponse

​Demand Fallback

​Qu’est-ce que l’intégration GAM Fallback ?

​Avantages

​À qui est-ce destiné ?

​Processus d’intégration

​Exemple de requête

​Exemple de réponse

Vue d’ensemble

Médiation de la demande

Qu’est-ce que la médiation de la demande ?

Fonctionnement de la facturation

Avantages

À qui est-ce destiné ?

Processus d’intégration

Implémentation API

Modifications de la requête

Modifications de la réponse

Cas d’erreur

Exemple de requête

Exemple de réponse

Demand Fallback

Qu’est-ce que l’intégration GAM Fallback ?

Avantages

À qui est-ce destiné ?

Processus d’intégration

Exemple de requête

Exemple de réponse