Solicitação e Resposta de Leilão de Marcas Patrocinadas

Os leilões de Marcas Patrocinadas funcionam enviando solicitações de leilão com detalhes de posicionamento e gatilhos de segmentação, e então recebendo respostas estruturadas contendo campanhas vencedoras com todos os ativos criativos e metadados necessários.

Modelos Disponíveis

As campanhas de Marcas Patrocinadas são criadas usando um dos três modelos pré-construídos:

Coleção de Produtos: Vários produtos exibidos em uma página de destino para descoberta abrangente de produtos
Destaque de Produto: Produto único e um criativo
Destaque da Loja: Direciona tráfego diretamente para a página da loja de um fornecedor para reconhecimento de marca

Solicitação de Leilão

As solicitações de leilão para Marcas Patrocinadas seguem o formato padrão de leilão com gatilhos específicos para segmentação e suporte para filtragem baseada em geolocalização:

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

Parâmetros da Solicitação

winners: Número de campanhas de marcas patrocinadas a retornar
placementId: Identificador do espaço de posicionamento de marcas patrocinadas
triggers: Critérios de segmentação usando um dos seguintes:
- products.ids: Array de IDs de produtos específicos para segmentar
- category.id: Categoria de produto para segmentação mais ampla
- searchQuery: Termos de pesquisa para segmentação baseada em palavras-chave
geoTargeting: Identificador de localização geográfica para filtragem de campanha baseada em localização
opaqueUserId: Identificador anônimo do usuário para personalização e segmentação aprimorada

Comportamento de Filtragem por Geolocalização

O sistema de leilão filtra automaticamente as campanhas com base na segmentação por geolocalização:

Correspondência de Localização: Campanhas com configurações específicas de geolocalização só participam quando o campo geoTargeting corresponde às suas localizações configuradas
Sem Geolocalização: Campanhas sem restrições de geolocalização participam de todos os leilões independentemente do valor geoTargeting
Várias Localizações: Campanhas direcionadas a várias localizações participam quando a solicitação corresponde a qualquer uma de suas localizações configuradas
Compatibilidade com Versões Anteriores: Campanhas existentes sem geolocalização continuam a funcionar como antes

Resposta do Leilão

A resposta do leilão retorna campanhas vencedoras de marcas patrocinadas com ativos criativos completos e metadados:

{
  "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
    }
  ]
}

Campos da Resposta

Objeto Winner

rank: Classificação de posição da campanha vencedora
resolvedBidId: Identificador único para rastreamento de lance e atribuição
productId: Identificador do produto principal da campanha
type: Tipo de campanha (sempre “product” para marcas patrocinadas)
id: Identificador da campanha
title: Título da campanha para fins de exibição
campaignId: UUID da campanha de marcas patrocinadas
productIds: Array de todos os produtos incluídos na campanha (1-5 produtos)

Array de Assets

Ativos criativos para renderizar o anúncio de marcas patrocinadas:

url: URL da CDN para o ativo
role: Tipo de ativo (“image” para banner criativo, “logo” para logotipo da marca)
contentType: Tipo MIME do ativo
contentLength: Tamanho do arquivo em bytes
width/height: Dimensões do ativo em pixels

Objeto Content

Conteúdo da campanha para renderização:

headline: Texto do título da campanha
brandName: Nome da marca ou fornecedor
creative1: URL de ativo criativo adicional (vídeos, imagens secundárias)

Notas de Implementação

Flexibilidade de Renderização

Os ativos criativos, título e productIds são retornados separadamente na resposta do leilão, permitindo que você renderize esses elementos de acordo com seus requisitos de design frontend. O array de assets contém todos os componentes criativos necessários com identificação clara de função.

Suporte Multi-Produto

As campanhas de marcas patrocinadas podem promover de 1 a 5 produtos simultaneamente. O array productIds contém todos os produtos incluídos na campanha, enquanto productId representa o produto principal para fins de rastreamento.

Integração de Modelos

Embora as campanhas sejam criadas usando modelos disponíveis (Coleção de Produtos, Destaque de Produto, Destaque da Loja), a resposta do leilão fornece todos os ativos e conteúdo necessários independentemente do modelo usado, garantindo integração consistente em todos os tipos de campanha.

Especificações de Conteúdo

Todos os ativos criativos (imagens e vídeos) carregados para campanhas de Marcas Patrocinadas devem atender a estes requisitos:

Formatos suportados: JPEG, PNG, WEBP, GIF, MP4
Tamanho máximo do arquivo: 5MB por criativo/vídeo

​Modelos Disponíveis

​Solicitação de Leilão

​Parâmetros da Solicitação

​Comportamento de Filtragem por Geolocalização

​Resposta do Leilão

​Campos da Resposta

​Objeto Winner

​Array de Assets

​Objeto Content

​Notas de Implementação

​Flexibilidade de Renderização

​Suporte Multi-Produto

​Integração de Modelos

​Especificações de Conteúdo