taskType ADS com uma de duas plataformas, e action escolhe o que ler. Para escolher entre as bibliotecas de anúncios, veja Bibliotecas de anúncios comparadas.
tiktok_ad_librarylê a Biblioteca de Anúncios do TikTok (a Commercial Content Library). Ela lista os anúncios exibidos em 34 regiões: os países da UE e do EEE, o Reino Unido, a Suíça, a Türkiye e o Brasil. Cada anúncio traz o primeiro e o último dia de exibição e uma faixa de impressões, eadacrescenta a página de destino, quem pagou, a segmentação e as impressões por país, idade e gênero. Use-a para ver todos os anúncios de um concorrente.tiktok_creative_centerlê os principais anúncios do TikTok Creative Center. Ele lista os anúncios que tiveram o melhor desempenho em um país nos últimos 7, 30 ou 180 dias, com taxa de cliques, curtidas e setor, para 28 países, incluindo EUA, Coreia e Japão. Use-o para ver quais criativos funcionam em um mercado.
advertisers e ad custam 0.5 crédito cada.
Biblioteca de Anúncios do TikTok
Requisição
GET /v1/async/task/{id} ou receba o webhook. Veja Tarefas assíncronas. Uma busca de 300 anúncios leva cerca de um minuto.
Analise os anúncios de um concorrente
Três requisições cobrem uma análise de concorrentes:advertiserscom o início do nome do concorrente retorna os nomes exatos e os IDs que a biblioteca conhece.searchcom esse nome emadvertiserNamelista os anúncios do anunciante.sortByos ordena por data de publicação, data da última exibição ou impressões,activeStatusmantém os anúncios ativos ou os que pararam, esummaryconta os formatos e os anúncios que começaram em cada semana.adcom olibraryIdde um anúncio retorna a página de destino, quem pagou, a segmentação, o tamanho do público e as impressões por país, idade e gênero.
query em vez de advertiserName: ele pesquisa o texto, as hashtags e os nomes dos anunciantes.
Parâmetros
action:search(padrão),advertisersouad.country: Obrigatório em todas as ações. Um deAT,BE,BG,BR,CH,CY,CZ,DE,DK,EE,ES,FI,FR,GB,GR,HR,HU,IE,IS,IT,LI,LT,LU,LV,MT,NL,NO,PL,PT,RO,SE,SI,SKeTR.ALLe países fora da lista, comoUS,KReJP, são recusados com400 VALIDATION_ERROR, porque a biblioteca cobre apenas essas regiões.query: Uma palavra-chave. Emsearch, corresponde ao texto, às hashtags e aos anunciantes por ordem de relevância, e a biblioteca conta no máximo 5,000 anúncios. Emadvertisers, é o início do nome de um anunciante e é obrigatório.searchprecisa dequeryouadvertiserName, e não de ambos.advertiserName: O nome exato de um anunciante, comoNIKE Retail B.V.. A biblioteca conta todos os anúncios dele.libraryId: O ID numérico de um anúncio, como1879578148398450.ado exige.activeStatus:all(padrão),activeouinactive.mediaType:all(padrão),videoouimage.startDate,endDate:YYYY-MM-DD. Mantém os anúncios exibidos entre os dois dias. O padrão são os últimos 365 dias.sortBy:published_desc(padrão),published_asc,last_shown_desc,last_shown_asc,impressions_descouimpressions_asc. Vale para uma busca poradvertiserName, e uma busca porquerysegue sempre a ordem de relevância.limit: De 1 a 300 anúncios. Padrão 30.cursor: OnextCursorde uma resposta anterior, para ler os anúncios seguintes.
search lê todos os campos acima, exceto libraryId. advertisers lê query e country, e ad lê libraryId e country. Um valor que a biblioteca não consegue pesquisar ou um campo que a ação não lê é recusado com 400 VALIDATION_ERROR, e details indica o campo.
Ler mais anúncios
Uma resposta com mais anúncios para ler traznextCursor. Envie-o como cursor com a mesma busca para receber os anúncios seguintes, de novo até limit. nextCursor é null quando a biblioteca não tem mais. Um cursor só funciona com a busca que o retornou: um query, advertiserName, country, activeStatus, mediaType, intervalo de datas ou sortBy diferente é recusado com 400 VALIDATION_ERROR, enquanto limit pode mudar. Em uma busca por query, que a biblioteca ordena por relevância, alguns anúncios no limite entre duas páginas podem se repetir ou ficar de fora; libraryId permite identificar as repetições.
Encontre um anunciante
action advertisers retorna até 20 anunciantes cujos nomes começam com query. Envie o nome exato como advertiserName para buscar os anúncios desse anunciante.
advertiserId e advertiserName. country, adCount e verified são null, porque as sugestões da biblioteca não informam mais. Uma busca de anunciantes custa 0.5 crédito.
Resposta da busca
- A resposta repete
platform,action,country,queryouadvertiserName,activeStatus,mediaTypeesortBy.totalCounté a contagem da biblioteca dos anúncios correspondentes, que para em 5,000 em uma busca porquery.returnedCountconta os anúncios emads,hasMoreétruequando a biblioteca tem mais, o quenextCursorlê, elibraryUrlabre a mesma busca na Biblioteca de Anúncios. - Cada anúncio tem
position,libraryId,libraryUrl,advertiserName,title,format(VIDEO,IMAGEouTEXT),images,videos(url,previewUrl),startDate,endDate,activeDays,impressions(min,max),estimatedAudience(a faixa da biblioteca, como400K-500K) eplatforms(TIKTOK). startDateeendDatesão o primeiro e o último dia em que a biblioteca mostra o anúncio (dias em UTC).activeDaysconta os dias destartDateaendDate, ambos incluídos. A biblioteca não informa o gasto.isActiveétrueoufalsequandoactiveStatuséactiveouinactive, enullquando éall.advertiserId,payer,linkUrl,landingDomain,utmetargetingsãonullem uma busca.ados preenche.summaryconta os anúncios desta resposta:ads,activeAds,advertisers(os 10 com mais anúncios),formats,platforms,oldestStartDate,newestStartDateemedianActiveDays, comlaunchesByWeek(os anúncios que começaram em cada semana ISO) elongestRunning(os 5 anúncios com maisactiveDays). Não temlandingDomainsnemutmCampaigns, porque uma busca não traz páginas de destino.- As URLs de imagens e vídeos são assinadas e expiram cerca de 5 a 6 horas após a leitura. Salve os arquivos de que precisar.
- Uma busca sem anúncios correspondentes termina com
adsvazio e umsummaryde0anúncios.
O que a biblioteca guarda
A biblioteca mostra os anúncios exibidos em suas 34 regiões e os guarda por cerca de 13 meses. Ela informa o primeiro e o último dia de exibição e uma faixa de impressões de cada anúncio. Não publica o gasto.Abra um anúncio
action ad abre o anúncio com o libraryId e o country que você enviar.
adtem os campos de um anúncio de busca, maislinkUrl,landingDomain,payer(quem pagou o anúncio),category,objective,ctaText,advertiserId,reachedCountriesetargeting.targetingtrazbyCountry(osagesegendersde cada país),provinces,cities,languages,interests,targetAudienceSize(a faixa da biblioteca, como15.5M-18.9M),customAudience,excludesAudience,highSpendingPower,operatingSystems,deviceModels,videoInteractionsecreatorInteractions. Uma parte que a biblioteca não publica para o anúncio énullou vazia.advertisertemadvertiserId,advertiserName,payer,registryCountrye aaccountdo TikTok por trás dos anúncios (username,displayName,verified,followers,accountType,profileUrl,avatarUrl).transparencytraztotalImpressionsebyCountry: asimpressionsde cada país e seusbreakdownsporageegender.- Um
libraryIdpara o qual a biblioteca não tem anúncio falha comPAGE_UNAVAILABLE.
TikTok Creative Center
O Creative Center lista os anúncios de melhor desempenho de um país, os anúncios que o TikTok seleciona para os últimos 7, 30 ou 180 dias. É uma amostra ranqueada, e não o conjunto completo de anúncios de um anunciante: o nome do anunciante costuma estar vazio, e a biblioteca não informa datas, gasto nem impressões. Ela informa a taxa de cliques, as curtidas, o nível de custo, o setor e os objetivos de cada anúncio. Use-o para descobrir quais ganchos, formatos e produtos funcionam em um mercado.Requisição
Parâmetros
action:search(padrão) ouad.advertisersé recusado com400 VALIDATION_ERROR, porque o Creative Center não tem busca de anunciantes.country: Obrigatório emsearch. Um deAE,AR,AU,BR,CA,CO,DE,ES,FR,GB,ID,IT,JP,KR,MX,MY,NL,PH,PK,RO,SA,SE,SG,TH,TR,US,VNeZA.ALLé recusado.query: Uma palavra-chave.period:7,30(padrão) ou180dias.industry: Um ID de setor, como21103000000(Hardware & Electrical), como oindustry.idde um anúncio o nomeia.objective:traffic,app_installs,conversions,video_views,reach,lead_generation,product_salesouapp_promotion.adLanguage: Um código de idioma:en,es,ar,vi,th,de,id,pt,fr,ms,nl,ja,it,ro,zh-Hantouko.adFormat:spark(anúncios que impulsionam a publicação de um criador) ounon_spark.sortBy:for_you(padrão),impression,ctr,play_2s_rate,play_6s_rate,cvroulike.limit: De 1 a 200 anúncios. Padrão 30.cursor: OnextCursorde uma resposta anterior.libraryId: O ID numérico de um anúncio do ranking.ado exige.
search lê todos os campos acima, exceto libraryId, e ad lê somente libraryId. O Creative Center lista no máximo cerca de 400 a 500 anúncios para um país, um período e um conjunto de filtros (totalCount).
Resposta da busca
- A resposta repete
platform,action,country,period,sortBye os filtros recebidos.totalCounté o número de anúncios do ranking para essa combinação. - Cada anúncio tem
position,libraryId,title,advertiserName(muitas vezesnull),format,ctrPercent(a taxa de cliques em porcentagem),costLevel,likes,industry(id,name),objectives,durationSeconds,width,height,voiceOver,images,videosevideoUrls(o arquivo de vídeo por resolução, como360pe1080p). - O Creative Center não informa
startDate,endDate,impressionsnemlibraryUrl, então esses campos sãonull, esummaryconta apenas os formatos, os anunciantes e as plataformas. - As URLs de vídeo e imagem são assinadas e expiram cerca de 5 a 6 horas após a leitura.
Abra um anúncio
action ad abre um anúncio do ranking por libraryId e acrescenta linkUrl, landingDomain, reachedCountries, comments, shares e source (onde o anúncio foi criado, como TikTok Ads Manager).
libraryId para o qual o Creative Center não tem anúncio falha com PAGE_UNAVAILABLE.
Preço
Uma busca reserva 0.5 crédito a cada 30 anúncios que olimit dela pede, e cobra 0.5 crédito a cada 30 anúncios que retorna, no mínimo 0.5 crédito. A busca padrão de 30 anúncios custa 0.5 crédito, e uma busca com limit 300 na Biblioteca de Anúncios reserva 5 créditos. advertisers e ad custam 0.5 crédito cada. Apenas requisições concluídas são cobradas.