Como exportar criativos de anúncios do Google e manter as evidências de origem

Definições

• Criativo: Um item de anúncio público. Não é uma campanha.
• ID de anunciante: Identidade de conta do Google para um anunciante.
• ID de criativo: Identidade do Google para um criativo sob um anunciante.
• Observação: Um registro de um criativo no momento da coleta.
• Ponteiro: Um link para um recurso remoto de mídia ou de pré-visualização.
• Manifesto: Um arquivo de configurações da coleta e de resumo.
• Variação: Um item de mídia ou de pré-visualização dentro de um registro de criativo. Não é necessariamente um teste de anúncio separado.
• Pré-visualização: Um recurso de origem usado para mostrar um criativo. Pode exigir renderização e nem sempre é um arquivo baixável.
• Actor: Um programa hospedado de coleta de dados.
• Task publicada: Uma configuração de Actor salva e pública.
• **`null`**: Nenhum valor utilizável está disponível. Não é zero.

Configuração e escopo da coleta

Para coletar dados de criativos, configure um Actor, como o Google Ads Transparency Scraper público. O Actor aceita de um a cem alvos, que podem ser nomes, domínios, IDs, URLs de anunciante ou URLs de criativo. A configuração `maxItems` varia de um a cinco mil, com um padrão de dez compartilhado entre todos os alvos.

A task publicada tem como padrão `nike.com`, região `ANYWHERE`, plataforma `ALL`, formato de anúncio `ALL`, detalhes de veiculação desativados e um limite de vinte itens Google Ads Creative Library Export | Ads Data. Pesquisas por domínio podem corresponder a múltiplas contas de anunciante, então você deve usar um ID de anunciante exato e verificado ou uma URL de anunciante exata e verificada ao investigar uma conta específica. Use uma pesquisa por domínio somente se você planeja revisar e separar as contas depois. Reduza o limite da coleta e mantenha os detalhes de veiculação desativados, a menos que a sua pesquisa exija especificamente metadados de veiculação. Filtros de data opcionais aceitam datas reais até hoje. Lembre-se de que um limite de coleta é um limite, não um histórico completo de anúncios.

Mapa de campos e limites dos dados

Cada linha salva mapeia campos de dados específicos da plataforma de origem. `advertiserId` e `creativeId` formam um par único de identidade de criativo. Você nunca deve identificar uma conta somente pelo nome da marca. `creativeUrl` aponta para a página pública de detalhes da origem. Tanto `mediaUrl` quanto `previewUrl` são ponteiros remotos de origem que podem retornar `null`, e uma pré-visualização pode ser um recurso JavaScript, e não um arquivo direto. A lista `variations` e `variationCount` registram ativos filhos aninhados, com suas URLs e dimensões, mas esses ativos filhos não são variantes independentes de campanha.

Os campos `firstShownAt` e `lastShownAt` fornecem datas públicas de exibição quando disponíveis, mas não garantem veiculação contínua nem o momento da coleta. O campo `approxDaysShown` é um valor aproximado da origem e não deve ser transformado em dias contínuos exatos, gasto com anúncios ou sucesso de campanha. O carimbo de data e hora `observedAt` registra quando o Actor coletou o registro. Os campos solicitados de região, plataforma e formato fornecem contexto da coleta, e não uma lista completa de locais de veiculação. Os campos `status` e `statusReason` indicam a qualidade da linha, em que `ok` significa coleta bem-sucedida e `partial` pode significar um formato ausente. Campos opcionais de pagador podem estar ausentes ou desativados, e um pagador não é necessariamente o anunciante. Além disso, o repositório de origem do Google pode expor campos específicos de local que este Actor não retorna Ajuda da transparência do Google Ads.

Chaves de observação e manifestos feitos pelo leitor

Os IDs de anunciante e de criativo devem ser tratados como um par, porque o mesmo ID de criativo sob dois anunciantes diferentes representa duas identidades distintas. O Actor remove duplicatas desse par somente dentro de uma única execução, ao passo que execuções posteriores retêm uma nova observação. Como a linha do Actor não fornece um ID de execução, você deve criar campos feitos pelo leitor.

Crie um `collection_batch_id` feito pelo leitor para o agrupamento do seu lote. Retenha o ID real da execução, a versão do build, a identidade do conjunto de dados, as configurações da coleta, os horários da coleta e o resumo da execução em um manifesto de coleta separado, feito pelo leitor. A chave de observação sugerida combina o ID do lote, o ID do anunciante e o ID do criativo. Mantenha os comprovantes internos da execução separados do seu relatório final de evidências.

Armazenamento de dados JSON e variações

JSON é um formato de dados em texto que preserva hierarquias estruturadas. Arquivos JSON completos preservam variações aninhadas, enquanto uma exportação CSV é apenas uma visualização opcional de tabela plana. Uma linha pai de observação pode conter linhas de variação aninhadas, mas essas variações filhas não são testes separados de criativo ou de campanha. Sempre preserve valores `null`, em vez de substituí-los por zero ou por dados inventados. Uma biblioteca de exibição é uma visão derivada, o que significa que você deve sempre preservar os arquivos originais de observação por baixo dela.

Método completo de coleta e retenção

1. Configure o escopo do alvo, a região, a janela de datas públicas e o limite de itens. Use um ID de anunciante exato e verificado ou uma URL de anunciante exata e verificada ao investigar uma conta específica e use pesquisas por domínio somente com revisão após a coleta. Mantenha os detalhes de veiculação desativados, a menos que sejam necessários.
2. Execute o Actor Google Ads Transparency Scraper usando as configurações da task publicada Google Ads Creative Library Export | Ads Data.
3. Registre a sua configuração de coleta em um manifesto feito pelo leitor. Armazene o ID da execução, a versão do build, a identidade do conjunto de dados, as configurações da coleta, os horários da coleta e o resumo da execução separadamente do seu relatório público de evidências.
4. Inspecione os campos de resumo de OUTPUT, incluindo `creativesSaved`, `duplicatesSkipped`, `unusableCreativesSkipped`, `stopReason` e `targetOutcomes`. Mantenha distintos os registros parciais, os alvos com falha, os resultados zero e as paradas por limite. Lembre-se de que um conjunto de dados de saída vazio ou reduzido não pode provar que um anunciante não veiculou anúncios.
5. Aplique a regra exata de aceitação: exija que `advertiserId`, `creativeId`, `creativeUrl` e `observedAt` não estejam em branco para uma observação identificada. Revise os campos `status` e `statusReason`. Preserve os valores explicitamente ausentes de `mediaUrl` ou `previewUrl`; não transforme `null` em zero nem invente um link. Coloque em quarentena as linhas com identidade ausente em um arquivo de revisão separado, em vez de mesclar valores em branco.
6. Crie colunas feitas pelo leitor, separadas dos campos do Actor. Atribua um `collection_batch_id` feito pelo leitor e construa a sua chave de observação combinando o ID do lote, o ID do anunciante e o ID do criativo.
7. Armazene arquivos JSON completos de observação para preservar as variações aninhadas. Retenha os registros de variação filha sob a linha pai de observação, sem contar os ativos filhos como testes independentes de criativo ou de campanha.
8. Faça e registre verificações de link independentes e separadas, com o horário da verificação, o tipo de ponteiro, o método e o resultado. Preserve os ponteiros anteriores quando novos ponteiros chegarem e mantenha os registros de observação mesmo quando os links remotos ficarem indisponíveis.
9. Anexe lotes posteriores de coleta sem substituir os seus arquivos anteriores de observação. Retenha os registros históricos junto com a exibição derivada da visão mais recente.
10. Entregue a sua biblioteca de origem finalizada, o manifesto de coleta, os registros datados de verificação de links e a visão mais recente derivada à etapa de relatório. Use o par original de ID de anunciante e de criativo para encontrar a origem de novo, parando antes de qualquer pontuação de criativo ou recomendação de campanha.

Verificações de link independentes e solicitações HTTP HEAD

Crie um registro separado de verificação de link que contenha a identidade pai e o lote, o tipo de ponteiro, o horário da verificação, o método e o resultado. Uma solicitação HTTP HEAD pede a um servidor apenas os cabeçalhos da resposta, e não o conteúdo do arquivo. Renderização significa exibir com sucesso uma pré-visualização dentro de um navegador. Um código de resposta HTTP 200 significa que o recurso respondeu naquela verificação, mas uma resposta `image/png` difere de uma resposta `application/javascript`.

Nenhuma dessas respostas prova uma imagem renderizada, arquivamento permanente de arquivo, direitos de reutilização ou disponibilidade duradoura. A pequena verificação de metadados de 13 de outubro de 2026 salvou duas observações `ok` de duas contas, mas as verificações de cabeçalho apenas provaram respostas datadas, e não um histórico repetido nem cobertura completa. Baixar ativos e renderizar pré-visualizações estão fora do escopo deste método de links de origem.

Anexar lotes posteriores e tratar ponteiros indisponíveis

Anexe lotes posteriores sem substituir os seus arquivos anteriores de observação. Uma exibição atual pode mostrar a observação mais recente por par de identidade, mas ela deve apontar de volta para os registros históricos. Quando um ponteiro antigo falhar, retenha o registro de origem dele, registre a verificação com falha e inspecione a página pública de origem em uma revisão autorizada posterior, se necessário. Um ponteiro com falha ou uma observação ausente por limite não prova que um anúncio foi excluído. Não adivinhe URLs nem tente recuperar anúncios excluídos. Como não foram feitos testes de execução repetida nem testes de longo prazo, o exemplo ensina somente o raciocínio de retenção.

Exemplo fictício e análise de contagens

Todos os registros e IDs neste exemplo são fictícios. A/B/C1/C2 são rótulos de ensino e não fixtures reais de origem. Nenhum arquivo de mídia é baixado.

Esta coleta produz 5 linhas de observação, calculadas como 3 linhas no lote S1 mais 2 linhas no lote S2 (3 + 2 = 5). Há 3 pares únicos de identidade de criativo: A:C1, A:C2 e B:C1. A soma das contagens de variação em todas as linhas retidas dá 6 observações de variação, calculadas como 2 mais 1 mais 1 mais 1 mais 1 (2 + 1 + 1 + 1 + 1 = 6). Essas observações de variação são ativos filhos dentro de registros pai, não 6 criativos únicos nem testes de anúncio separados.

Uma visão do mais recente por identidade contém 3 linhas correspondentes às 3 identidades únicas, com duas verificações de link disponíveis e datadas e uma verificação indisponível. O anunciante B:C1 continua representado pela observação S1 dele, e a ausência dele no lote S2 não prova a exclusão do anúncio. Todas as 5 observações devem ser mantidas na biblioteca. Esta retenção de registros preserva registros de evidência e ponteiros sem afirmar histórico completo de anúncios, armazenamento permanente de arquivos de mídia, sucesso do anúncio ou resultados de testes ao vivo de execução repetida.

A visibilidade pública não concede uma permissão geral de reutilização Termos do Google: Outro conteúdo. Este método retém registros de origem e ponteiros; baixar ou republicar ativos está fora deste fluxo de trabalho de links de origem.