Kwai Ads
O Kwai é o único conector da plataforma que não usa login automático. Não existe botão de autorizar: as credenciais são emitidas pelo Kwai, por e-mail, e digitadas no caOS. Por isso o passo mais importante acontece fora da tela.
Começar
Conectaro único que pede credencial
Aqui quem age é o cliente, na plataforma dele: só ele pode pedir as credenciais ao Kwai. Você não consegue fazer isso por ele, e não há botão no caOS que substitua esse pedido. O que você faz é receber os três valores e colá-los.
Peça ao contato do cliente no Kwai Ads três itens: Client ID, Client Secret e Refresh Token. São os mesmos três que qualquer plataforma de dados pede, e chegam na resposta de e-mail do Kwai.
Peça a autorização como channel advertiser developer, declarando que os dados serão compartilhados com o caOS. Esse detalhe decide se a conexão vai funcionar sozinha. O Kwai emite credenciais em mais de um tipo, e só as desse tipo conseguem listar as contas pelo identificador do caOS. Credencial emitida como agency developer conecta, mas exige um campo a mais, explicado em Quando dá errado.
Na tela de nova fonte, escolha Kwai Ads, cole os três valores e dê um nome ao login. Ao confirmar, o caOS testa a credencial contra o Kwai antes de gravar qualquer coisa: credencial recusada não vira registro.
O que é sucesso: as contas daquela credencial aparecem na lista, com nome, moeda e razão social, já vinculadas a uma tag com o nome do login.
Sua credencial, e o que acontece com ela
O Kwai é a exceção da plataforma. Nos outros conectores a credencial se renova sozinha para sempre. Aqui o Refresh Token vale 360 dias e não se renova: o cliente precisa pedir um novo ao Kwai, por e-mail, respondendo a mesma thread de onboarding.
Trocar o valor não custa nada e não perde nada: o valor novo entra em Credenciais · Renovar token, sem recadastrar o cliente e sem perder as contas já vinculadas. Uma credencial vencida aparece na lista com o selo token expirado.
A credencial fica cifrada de ponta a ponta. Ela é cifrada antes de ser gravada, e a chave não vive no banco: nem quem tem acesso ao banco lê o valor. Ninguém no caOS, nem você, vê a credencial de volta depois de salva; a tela mostra apenas que ela existe e está válida.
Só é lida a métrica que você pediu. O caOS não escreve na sua conta de anúncio para extrair dados, e não guarda dado pessoal de quem viu o anúncio. O tratamento segue a LGPD, e a exclusão é sua: revogar a conexão apaga a credencial guardada.
Referência
Métricas e dimensõeso que cada campo quer dizer
O Kwai nomeia os campos de um jeito próprio: impressão se chama exposure, e as métricas de vídeo começam com photo. Vale conferir a tabela antes de montar o primeiro relatório.
Métricas principais9 de 99
| Campo na API | O que é | Onde aparece |
|---|---|---|
| cost | Investimento, na unidade menor da moeda. | Investimento no Pacer e no Xtractor, já convertido. Ver a nota sobre unidade, abaixo. |
| exposure | Quantas vezes o anúncio foi exibido. | É o campo de impressões do Kwai. O nome não ajuda. |
| click | Cliques no anúncio. | Cliques. Singular, sem o s. |
| photoThruPlayCnt | ThruPlay: assistiu o vídeo inteiro ou pelo menos alguns segundos. | É o que o time definiu como visualização de vídeo do Kwai. Não é conclusão de 100%. |
| photo25percentPlayCnt | Chegou a 25% do vídeo. Há também 50 e 75. | Use para curva de retenção. |
| photoAvgPlayTime | Tempo médio assistido. | Bom para comparar criativos entre si. |
| ctr | Cliques ÷ impressões. | CTR. O Pacer recalcula a partir das somas. |
| cpm | Custo por mil impressões. | CPM, também recalculado. |
| cpc | Custo por clique. | CPC, também recalculado. |
Dimensões4
| Campo na API | O que é | Onde aparece |
|---|---|---|
| date | O dia da linha. | Desempenho vem sempre por dia. |
| account_id | A conta de anúncio. | Vem com a razão social e a moeda. |
| campaign_id | A campanha. | Existe também o nível de conjunto e o de criativo. |
| creative_id | O criativo, que no Kwai é o próprio anúncio. | O Kwai não tem um nível de anúncio separado do criativo. |
Parâmetros do relatório
Os campos acima dizem o que volta. Estes parâmetros dizem como: eles decidem o grão da linha, o período que ela cobre e o que conta como conversão. Dois relatórios da mesma conta com números diferentes quase sempre diferem aqui.
| Parâmetro | O que muda | Valores |
|---|---|---|
| endpoint do report | O nível de cada linha. | Um endereço por nível: conta, campanha, conjunto, criativo, vídeo, público e app. Não é um parâmetro, é a chamada que muda. |
| timeRange | O período. | Vem da fonte. O Kwai devolve o dia já alinhado ao fuso da conta. |
| granularidade | A agregação. | Diária. O Kwai não oferece recorte por hora nos relatórios que o caOS usa. |
| unidade de custo | Como o valor chega. | Convertido pelo caOS antes de gravar. Ver a nota de unidade acima antes de consultar a API por fora. |
Tudo que dá para puxar
As tabelas acima são as que a maior parte dos relatórios usa, mas você não está preso a elas. O catálogo inteiro do Kwai tem 16 tabelas e 766 campos, e ao montar a fonte você escolhe o que entra. O que aparece marcado como puxada por padrão é o que a fonte de exemplo usa; o resto está disponível do mesmo jeito.
A lista abaixo sai do próprio catálogo do Xtractor, o mesmo que a tela de nova fonte lê. Se um campo está aqui, a tela oferece.
creative_effect_daily104 campos
accountId, creativeId, creativeName, unitId, campaignId, photoId, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
unit_effect_daily102 campos
accountId, unitId, unitName, campaignId, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
app_target_effect_daily101 campos
accountId, appId, countryCode, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
campaign_effect_daily101 campos
accountId, campaignId, campaignName, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
population_analysis_effect_daily101 campos
accountId, countryCode, osType, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
photo_effect_daily100 campos
accountId, photoId, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
account_effect_daily puxada por padrão99 campos
accountId, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
apps12 campos
accountId, appId, appName, appIconUrl, appPlatform, appMarketLink, appPackageName, tracingType, trackingProvider, impressionUrl, clickUrl, createTime
audiences8 campos
accountId, orientationId, orientationName, populationType, status, coverNum, recordSize, createTime
avatars7 campos
accountId, avatarId, avatarType, description, avatarUrl, usedCount, createTime
units7 campos
accountId, unitId, unitName, campaignId, bidType, status, createTime
campaigns6 campos
accountId, campaignId, campaignName, marketingGoal, status, createTime
playables6 campos
accountId, playableId, playableName, thumbnailUrl, playableUrl, createTime
interaction_addons5 campos
accountId, materialId, materialName, materialType, createTime
pixels4 campos
accountId, pixelId, name, createTime
account_list3 campos
accountId, accountName, corporationName
Você não converte nada. O valor chega ao seu destino já na moeda da conta: o caOS converte antes de gravar. Isso importa porque a unidade de origem é um ponto em aberto: a documentação do Kwai diz que os campos de custo vêm em centavos, e a conversão que usamos, validada contra dado real de duas contas, divide por 1.000.000. Quem consultar a API por fora do caOS deve conferir o resultado contra um dia de gasto conhecido, em vez de confiar em qualquer um dos dois números.
O Kwai não expõe alcance. Nenhuma métrica de alcance ou frequência existe na API, diferente de Meta e TikTok. Relatório que depende de alcance precisa tratar o Kwai à parte.
Saída
Onde os dados chegamplanilha e banco são coisas diferentes
Planilha do Google
Para quem monta relatório na mão
Marque investimento, exposure (que é impressões), click e o nome da campanha. Os nomes dos campos são os do Kwai, então vale renomear as colunas no seu relatório.
Para vídeo, o campo que o time usa como visualização é o de ThruPlay, não o de conclusão.
BigQuery
Para quem vai modelar em cima
16 conjuntos de dados. Os de desempenho vêm por dia, e você escolhe o nível: conta, campanha, conjunto, criativo, vídeo ou análise de público.
Junto vêm as tabelas de cadastro: campanhas, conjuntos, criativos, apps, públicos, pixels e a lista de contas.
Confiança
Atualização do dadopor que o número de ontem ainda muda
Plataforma de anúncio reescreve o passado. Conversão que só é atribuída dias depois, gasto revisado, linha corrigida: o número de terça-feira muda na quinta. Se a extração só trouxesse o dia novo, sua planilha ficaria congelada no primeiro valor e passaria a divergir da plataforma sem ninguém perceber.
Por isso o caOS relê os últimos 30 dias a cada sincronização, e reescreve o que mudou. O histórico mais antigo continua no destino e não é tocado. Na prática: o que está na sua planilha ou no seu banco é o que a plataforma diz hoje, não o que ela dizia no dia da primeira carga.
Detalhe
Bom sabero que costuma gerar dúvida
O Kwai mantém um único token de acesso vivo por aplicação. Se a mesma credencial for usada por outra ferramenta ao mesmo tempo, uma derruba a outra. Na prática isso é tratado pela plataforma, mas explica falhas intermitentes quando a mesma credencial está em uso fora do caOS.
O criativo é o anúncio. O Kwai não tem um nível de anúncio separado, então o identificador do criativo é o que faz o papel de identificador do anúncio.
Suporte
Quando dá erradoa mensagem e o que fazer
“O Kwai não aceita o Corp ID do caOS nesta credencial.” Não é credencial inválida: significa que ela foi emitida como agency developer, e esse tipo lista as contas por um identificador próprio. A tela revela então o campo Agent ID, um número que veio no mesmo e-mail do Kwai, junto das credenciais. Preencha e confirme de novo. O acesso aos dados não é afetado.
“O Kwai recusou esse refresh token.” O valor colado não é o mais recente, ou não é par deste Client ID. Confira o e-mail mais novo do Kwai.
“O Kwai recusou o par Client ID + Secret.” O problema não é o token, que nem chegou a ser testado. A credencial inteira precisa ser reemitida.
“Nada a cadastrar: todas as contas já pertencem a credenciais ativas.” Esse cliente já está conectado. Se a intenção era renovar o token, use Renovar token na credencial existente; se era substituí-la, revogue a antiga primeiro.
Revogar uma credencial apaga o Client ID, o Secret e o Refresh Token guardados, e desvincula as contas. Tenha os três valores em mãos antes de revogar.