Saltar para o conteúdo 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.

​
Visão geral

Para lançar anúncios offsite em uma plataforma específica, o marketplace concede ao Topsort acesso às contas de anúncios necessárias, implementa o rastreamento de eventos offsite e o Topsort cuida do restante da integração (por exemplo, sincronização de catálogo e eventos offline com o marketplace, validação). O Topsort executa um cronograma de implementação de 2 semanas para cada plataforma offsite (por exemplo, Google ou Meta) para garantir um lançamento POC bem-sucedido, com recursos cross-funcionais dedicados do cliente:
  • Engenharia: ~1 dia de esforço de um engenheiro do marketplace (integração e validação). O desenvolvimento provavelmente pode ser concluído em uma única chamada de 90 minutos com engenheiros do Topsort.
  • Ad Operations: ~1 dia de suporte de ad ops do marketplace para configuração de campanhas, QA e lançamento.

​
Arquitetura de contas

O provisionamento automatizado de contas escala para milhares de vendedores com separação clara de orçamento e configuração manual mínima. Abaixo está a estrutura de contas recomendada.

​
Google

  • O marketplace fornece: Acesso ao MCC (conta administradora) + MCA (conta multicliente do Merchant Center)
  • O Topsort cria: Contas do Google Ads por vendedor com a vinculação necessária ao Merchant Center

​
Meta

  • O marketplace fornece: Acesso ao Business Manager principal
  • O Topsort cria: Business Manager filho e conta de anúncios por vendedor

​
TikTok

  • O marketplace fornece: Acesso ao TikTok Business Center / Business Manager, com permissão para gerenciar contas de anunciantes e assets
  • O Topsort cria: Uma conta de anúncios TikTok dedicada para a integração offsite do Topsort, normalmente uma conta de anúncios para o marketplace/varejista, não uma por vendedor

​
Snap

  • O marketplace fornece: Acesso ao Snap Business Manager / Organization, com permissão para gerenciar contas de anúncios e billing/assets
  • O Topsort cria: Uma conta de anúncios Snap dedicada para a integração offsite do Topsort, normalmente uma conta de anúncios para o marketplace/varejista, não uma por vendedor

​
Etapas de configuração

​
Configuração de contas

​
Acesso às contas (marketplace)

O marketplace concede ao Topsort acesso de administrador às contas de plataforma de anúncios de nível superior necessárias para os canais sendo integrados. Consulte Arquitetura de contas acima para as contas específicas às quais conceder acesso em cada plataforma.

​
Criação de contas (Topsort)

O Topsort provisiona a estrutura de contas em nível de vendedor sob esses contêineres do marketplace, incluindo contas de anúncios filhas, business managers ou contas do Merchant Center necessárias para a integração. Consulte Arquitetura de contas acima para o que o Topsort cria em cada plataforma. O marketplace pode fornecer ao Topsort uma lista de vendedores a habilitar para offsite.

​
Sincronização de catálogo (Topsort)

Quando formatos offsite baseados em catálogo estão no escopo, o Topsort sincroniza o catálogo do marketplace com a plataforma offsite, mapeando os produtos de cada vendedor na estrutura de conta da plataforma correspondente para esse vendedor.

​
Configuração de rastreamento de eventos (marketplace)

A única área em que o marketplace precisará fazer desenvolvimento é o rastreamento de eventos. Para reportar eventos offsite, use o mesmo endpoint /v2/events dos eventos onsite, passando parâmetros adicionais no corpo da solicitação.

​
ID de usuário opaco

O mesmo opaqueUserId usado para eventos onsite também deve ser reutilizado para atribuição offsite. Não é necessário um identificador offsite separado. O Topsort precisa de um identificador de usuário persistente e seguro para privacidade para conectar cliques e compras entre canais. Os mesmos requisitos onsite se aplicam ao uso offsite:
  • Persistência: Deve permanecer estável durante a janela de atribuição (normalmente 7–30 dias).
  • Consistência: O mesmo usuário deve receber o mesmo ID em visitas e canais quando possível.
  • Seguro para privacidade: Não deve conter PII como email, número de telefone ou nome.

​
URL de clique

A URL que o usuário tem ao chegar ao seu site a partir de um clique de anúncio offsite terá parâmetros de consulta importantes anexados. Exemplo de URL de clique: 
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
Parâmetros de consulta:
  • gclid — ID de clique anexado pelo Google
  • externalCampaignId e externalVendorId — parâmetros de consulta contendo o ID da campanha e o ID do vendedor do Topsort, anexados pelo Topsort. Devem persistir junto com o estado de atribuição do usuário por pelo menos a duração da janela de atribuição (configurável 7–30 dias). Devem sobreviver à navegação e visitas repetidas para que eventos de compra subsequentes possam ser corretamente vinculados ao clique de anúncio offsite originador.

​
Reportar cliques

Envie o evento abaixo quando um usuário chegar ao seu site a partir de um clique de anúncio offsite. Todos os campos são obrigatórios. 
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"
    }
  ]
}

​
Reportar compras

Todos os campos são obrigatórios. 
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
        }
      ]
    }
  ]
}

​
Compartilhar eventos com plataformas offsite

O cliente não precisa reportar separadamente eventos de conversão à plataforma offsite. O Topsort envia automaticamente eventos de compra elegíveis vinculados ao ID de clique correspondente (por exemplo, Google Click ID ou GCLID) por meio da API de conversões offline da plataforma.

​
Cronograma de integração

​
Semana 1 – Acesso e configuração de rastreamento de eventos

  • Conceder acesso às contas necessárias
  • Iniciar a implementação do rastreamento de eventos
  • Sincronizar catálogo se necessário com a plataforma offsite
  • Iniciar a configuração inicial do sistema

​
Semana 2 – Integração e configuração de dados

  • Finalizar a integração e iniciar testes
  • Validar rastreamento de eventos e estrutura/qualidade do catálogo
  • Após tudo configurado, validar com uma campanha ao vivo e monitorar desempenho