📖 Como Enviar UTMs para o Kwai via Webhook na Utmize

Visão Geral

Para que a Utmize envie corretamente eventos de pixel para o Kwai, é fundamental enviar os parâmetros UTM no formato esperado.
O backend valida e descompacta esses campos, e em caso de erro (especialmente em modo de teste), retorna mensagens detalhadas para facilitar o ajuste da integração.

🎯 Formato Esperado dos UTMs

utm_source

• Formato esperado:

  ad_delivery_platform|public_pixel_id

• ad_delivery_platform: Nome da plataforma de entrega do anúncio (ex: kwai)

• public_pixel_id: O identificador público do pixel cadastrado na Utmize (ex: P6840023f8572a0.15411956)

• Exemplo válido:

  kwai|P6840023f8572a0.15411956

utm_medium

• Formato esperado:

  campaignId|adSETID|creativeId|click_id|pixel_id

• campaignId: ID da campanha

• adSETID: ID do conjunto de anúncios

• creativeId: ID do criativo

• click_id: ID do clique (usado para rastreamento e validação de teste)

• pixel_id: ID do pixel (não é o public_id)

• Exemplo válido:

  123456|654321|999888|CLIQUE123|PIXELID123

🧪 Retornos em Modo de Teste (test_flag: true)

Quando você envia test_flag: true, o backend valida os campos e retorna mensagens detalhadas caso algo esteja fora do padrão:

• Se o utm_source estiver incorreto:

  {
    "message": "O teste foi identificado, mas o pixel não foi encontrado.",
    "notes": "Os dados do webhook foram armazenados, mas o evento não foi enviado porque o pixel não pôde ser localizado. No parâmetro `utm_source`, esperamos o formato `ad_delivery_platform|public_pixel_id`. Note que o `public_pixel_id` é diferente do `pixel_id`; ele é o identificador usado para localizar o pixel em nosso banco de dados. Por favor, envie parâmetros válidos de `ad_delivery_platform` e `public_pixel_id`."
  }

• Se o utm_medium estiver incorreto ou faltar algum campo:

  {
    "message": "O teste foi identificado, mas o click_id não foi informado.",
    "notes": "Os dados do webhook foram armazenados, mas o evento não foi enviado porque o click_id não foi informado. Se estiver usando Kwai Ads, esperamos o seguinte formato em utm_medium: campaignId|adSETID|creativeId|click_id|pixel_id."
  }

• Se tudo estiver correto:

  {
    "message": "Evento de teste enviado com sucesso para o Kwai.",
    "notes": "O payload do webhook foi armazenado e o evento foi enviado para o Kwai em modo de teste. Certifique-se de que o parâmetro `click_id` contém o valor correto de `test_id` para validação do rastreamento."
  }

📋 Resumo dos Campos

🕵️‍♂️ Onde encontrar o public_pixel_id?

• No painel Utmize, na área de Pixels, copie o campo Public ID do pixel Kwai desejado.

⚠️ Observações

• O backend descompacta os campos automaticamente, separando por | e atribuindo cada parte ao seu respectivo campo.

• Se algum campo estiver fora do padrão, o retorno de erro explicará exatamente o que está faltando ou incorreto.

• Sempre utilize o formato exato para garantir o rastreamento correto e facilitar a homologação.

🆘 Suporte

Em caso de dúvidas, envie o payload de teste e a resposta recebida para o suporte Utmize.
Assim, nossa equipe pode ajudar a ajustar rapidamente sua integração!

Seguindo este padrão, sua integração com o Kwai via Utmize será validada e rastreada corretamente!