Passer au contenu principal

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.

​
Aperçu

Pour lancer des annonces offsite sur une plateforme donnée, le marketplace accorde à Topsort l’accès aux comptes publicitaires requis, met en place le suivi des événements offsite et Topsort gère le reste de l’intégration (par exemple, synchronisation du catalogue et des événements offline avec le marketplace, validation). Topsort exécute un calendrier d’implémentation de 2 semaines pour chaque plateforme offsite (par exemple, Google ou Meta) afin d’assurer un lancement POC réussi, avec des ressources cross-fonctionnelles dédiées du client :
  • Ingénierie : ~1 jour d’effort d’un ingénieur marketplace (intégration et validation). Le développement peut probablement être terminé lors d’un seul appel de 90 minutes avec les ingénieurs Topsort.
  • Ad Operations : ~1 jour de support ad ops marketplace pour la configuration des campagnes, le QA et le lancement.

​
Architecture des comptes

L’approvisionnement automatisé des comptes s’adapte à des milliers de vendeurs avec une séparation claire des budgets et une configuration manuelle minimale. Voici la structure de comptes recommandée.

​
Google

  • Le marketplace fournit : Accès au MCC (compte administrateur) + MCA (compte multiclient Merchant Center)
  • Topsort crée : Comptes Google Ads par vendeur avec le lien Merchant Center requis

​
Meta

  • Le marketplace fournit : Accès au Business Manager parent
  • Topsort crée : Business Manager enfant et compte publicitaire par vendeur

​
TikTok

  • Le marketplace fournit : Accès au TikTok Business Center / Business Manager, avec permission de gérer les comptes annonceurs et les assets
  • Topsort crée : Un compte publicitaire TikTok dédié pour l’intégration offsite Topsort, généralement un compte publicitaire pour le marketplace/distributeur, pas un par vendeur

​
Snap

  • Le marketplace fournit : Accès au Snap Business Manager / Organization, avec permission de gérer les comptes publicitaires et la facturation/assets
  • Topsort crée : Un compte publicitaire Snap dédié pour l’intégration offsite Topsort, généralement un compte publicitaire pour le marketplace/distributeur, pas un par vendeur

​
Étapes de configuration

​
Configuration des comptes

​
Accès aux comptes (marketplace)

Le marketplace accorde à Topsort un accès administrateur aux comptes de plateforme publicitaire de niveau supérieur requis pour les canaux en cours d’intégration. Consultez Architecture des comptes ci-dessus pour les comptes spécifiques auxquels accorder l’accès sur chaque plateforme.

​
Création de comptes (Topsort)

Topsort provisionne la structure de comptes au niveau vendeur sous ces conteneurs marketplace, y compris les comptes publicitaires enfants, business managers ou comptes Merchant Center nécessaires à l’intégration. Consultez Architecture des comptes ci-dessus pour ce que Topsort crée sur chaque plateforme. Le marketplace peut fournir à Topsort une liste de vendeurs à activer pour offsite.

​
Synchronisation du catalogue (Topsort)

Lorsque des formats offsite basés sur le catalogue sont concernés, Topsort synchronise le catalogue du marketplace avec la plateforme offsite, en mappant les produits de chaque vendeur dans la structure de compte de plateforme correspondante pour ce vendeur.

​
Configuration du suivi des événements (marketplace)

Le seul domaine où le marketplace devra développer est le suivi des événements. Pour signaler des événements offsite, utilisez le même endpoint /v2/events que pour les événements onsite, en passant des paramètres supplémentaires dans le corps de la requête.

​
ID utilisateur opaque

Le même opaqueUserId utilisé pour les événements onsite doit également être réutilisé pour l’attribution offsite. Aucun identifiant offsite séparé n’est requis. Topsort a besoin d’un identifiant utilisateur persistant et respectueux de la vie privée pour relier clics et achats entre canaux. Les mêmes exigences onsite s’appliquent à l’usage offsite :
  • Persistance : Doit rester stable pendant la fenêtre d’attribution (généralement 7–30 jours).
  • Cohérence : Le même utilisateur doit recevoir le même ID sur les visites et canaux lorsque possible.
  • Respect de la vie privée : Ne doit pas contenir de PII telles qu’email, numéro de téléphone ou nom.

​
URL de clic

L’URL que l’utilisateur a lorsqu’il arrive sur votre site depuis un clic d’annonce offsite comportera des paramètres de requête importants. Exemple d’URL de clic : 
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
Paramètres de requête :
  • gclid — ID de clic attaché par Google
  • externalCampaignId et externalVendorId — paramètres de requête contenant l’ID de campagne et l’ID vendeur Topsort, attachés par Topsort. Doivent persister avec l’état d’attribution de l’utilisateur pendant au moins la durée de la fenêtre d’attribution (configurable 7–30 jours). Doivent survivre à la navigation et aux visites répétées pour que les événements d’achat ultérieurs puissent être correctement reliés au clic d’annonce offsite d’origine.

​
Signalement des clics

Envoyez l’événement ci-dessous lorsqu’un utilisateur arrive sur votre site depuis un clic d’annonce offsite. Tous les champs sont obligatoires. 
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"
    }
  ]
}

​
Signalement des achats

Tous les champs sont obligatoires. 
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
        }
      ]
    }
  ]
}

​
Partage des événements avec les plateformes offsite

Le client n’a pas besoin de signaler séparément les événements de conversion à la plateforme offsite. Topsort envoie automatiquement les événements d’achat éligibles liés à l’ID de clic correspondant (par exemple, Google Click ID ou GCLID) via l’API de conversions offline de la plateforme.

​
Calendrier d’intégration

​
Semaine 1 – Accès et configuration du suivi des événements

  • Accorder l’accès aux comptes requis
  • Lancer la mise en place du suivi des événements
  • Synchroniser le catalogue si nécessaire avec la plateforme offsite
  • Commencer la configuration initiale du système

​
Semaine 2 – Intégration et configuration des données

  • Terminer l’intégration et commencer les tests
  • Valider le suivi des événements et la structure/qualité du catalogue
  • Une fois tout configuré, valider avec une campagne en direct et surveiller les performances