Bem-vindo à API de relatórios da Singular, que oferece estatísticas agregadas sobre suas campanhas de marketing que podem ser ingeridas em seus sistemas internos de BI ou painéis de desempenho de marketing.
Este guia explica a API de relatórios da Singular, como entender seu caso de uso e como começar a executar consultas.
Leia este guia primeiro e, em seguida, reveja oReportingAPI Reference para obter os detalhes técnicos.
Procurando por outra API?
- Para relatórios SKAN, utilize a API SKAdNetwork.
- Para relatórios de receita de anúncios, use a API de monetização de anúncios.
- A Singular também oferece uma API GDPR e uma API para gerenciar links de rastreamento.
Ou um recurso diferente?
- A Singular também oferece Singular Data Destinations (ETL): um serviço premium que fornece uma forma mais fácil de exportar dados regularmente da Singular para a sua base de dados ou plataforma de BI.
- A API de relatórios oferece apenas dados agregados. Para exportar dados no nível do usuário do serviço de atribuição da Singular, consulte a FAQ Exportar logs e dados no nível do usuário.
Primeiros passos: Entendendo seu caso de uso
A Singular coleta e sintetiza dados de diferentes origens (recomendamos a leitura de Understanding Singular Reporting Data para uma revisão aprofundada).
Ao usar a API de relatórios, é possível escolher se deseja ver:
- Dados agregados de suas redes de anúncios e agências parceiras, como o custo da campanha;
- Dados agregados do seu rastreadorde atribuição/MMP, que pode ingerir no seu sistema de BI e juntar aos dados da rede, conforme necessário;
- Ou dados combinados, que são o resultado da junção inteligente de dados da rede e do rastreador da Singular para permitir que você analise seu ROI com a maior granularidade possível.
Embora todas as consultas sejam executadas através do mesmo endpoint (Criar relatório assíncrono), elas diferem nos campos que você inclui na consulta.
Para começar, entenda o que você deseja obter da API:
Seu caso de uso: |
Veja: |
|
|
|
Consulta de dados do rastreador e de dados da rede separadamente |
|
Os tipos de dados disponíveis através da API de relatórios
Consulta de dados de rede
Os dados de rede incluem estatísticas de campanha ingeridas de todas as redes de anúncios que você configurou no Singular. Eles não incluem dados de seu rastreador de atribuição (se você tiver configurado algum em Singular).
Por exemplo, você pode executar uma consulta para ver o custo (adn_cost) de cada uma de suas campanhas (adn_campaign_id) em um determinado intervalo de datas.
Campos disponíveis para dados de rede
Consulte a página Métricas e dimensões para obter uma descrição de cada campo.
Dimensões básicas (devem estar disponíveis para todas as redes):
- app
- fonte
- adn_campaign_id
- nome_da_campanha
- adn_campaign_url
- data_connector_id
- nome_da_fonte_do_conector_de_dados
- nome de utilizador do conetor de dados
- data_connector_timestamp_utc
Dimensões adicionais opcionais (o suporte varia consoante a rede):
- os
- plataforma
- campo_país
- region_field
- campo_cidade
- campo_id_dma
- campo nome_da_dma
- nome_da_sub_rede_adn
- adn_account_id
- nome_da_conta_adn
- adn_sub_campaign_id
- nome_da_subcampanha
Detalhamento de palavra-chave e/ou editor (o suporte varia de acordo com a rede, não pode ser obtido na mesma consulta que o detalhamento criativo):
- keyword_id
- palavra-chave
- publisher_id
- publisher_site_id
- nome_do_site_do_editor
Repartição criativa (o suporte varia consoante a rede, normalmente não pode ser obtido na mesma consulta que a palavra-chave/editor):
- creative_type
- adn_creative_id
- adn_creative_name
- creative_url
- creative_image
- creative_text
- largura_da_criatividade
- altura_da_criatividade
- creative_is_video
- asset_id
- nome_do_activo
Propriedades da campanha (saiba mais):
- bid_type
- bid_strategy
- bid_amount
- objetivo da campanha
- tipo_de_licitação padronizado
- estratégia_de_licitação padronizada
- valor_da_oferta_original
- estado_da_campanha
- min_roas
- moeda_de_metadados_original
Dimensões personalizadas:
Se você tiver definido dimensões personalizadas com base nessas dimensões de rede padrão, poderá extraí-las usando suas IDs. Use o Ponto de extremidade de dimensões personalizadas para obter todas as dimensões personalizadas definidas em sua conta e suas IDs.
- adn_cost
- adn_original_cost
- adn_original_currency
- adn_impressões
- adn_clicks
- adn_instalações
Observações:
- O Singular tenta fornecer o nível mais alto de granularidade disponível, mas nem todas as redes fornecem todas as dimensões. Consulte Conectores de dados em detalhes para obter mais informações sobre quais dados o Singular extrai de cada fonte.
- Estatísticas como impressões, cliques e instalações relatadas por uma rede de anúncios podem não corresponder às estatísticas relatadas pelo seu rastreador de atribuição.
Consultando dados do rastreador e dados da rede separadamente
Você pode usar a API para extrair dados do rastreador - estatísticas do serviço de atribuição do Singular ou de um rastreador de atribuição de terceiros que você configurou no Singular (como o Appsflyer ou o Google Analytics).
Por exemplo, você pode executar uma consulta para ver os cliques (tracker_clicks) e instalações (tracker_installs) para cada uma de suas campanhas (tracker_campaign_id) em um determinado intervalo de datas. As estatísticas do rastreador também incluem eventos pós-instalação e receita.
Depois de executar uma consulta nos dados do rastreador, é possível juntá-los aos dados da rede para poder calcular o CPI ou o ROI da campanha.
No entanto, a execução de um relatório combinado é normalmente uma forma mais fácil de obter o mesmo resultado.
Campos disponíveis para dados do rastreador
Consulte a página Métricas e dimensões para obter uma descrição de cada campo.
Dimensões básicas (devem estar disponíveis para todas as redes):
- app
- fonte
- tracker_campaign_id
Dimensões adicionais opcionais (o suporte varia de acordo com o rastreador):
- tracker_campaign_name
- sistema operativo
- plataforma
- campo_país
Dimensões personalizadas:
Se você definiu dimensões personalizadas com base nessas dimensões padrão do rastreador, é possível extraí-las usando suas IDs. Use o Ponto de extremidade de dimensões personalizadas para obter todas as dimensões personalizadas definidas em sua conta e suas IDs.
Métricas básicas:
- tracker_impressions
- tracker_clicks
- tracker_installs
- tracker_conversions
- tracker_reengagements
- utilizadores_activos_diários
Métricasde coorte:
- receita
- original_revenue
Para obter uma lista completa das métricas de coorte que você pode usar, consulte o Ponto de extremidade das métricas de coorte. Para obter mais informações, consulte O que são métricas de coorte?
Observe que as métricas de coorte incluem cálculos baseados em proporção, como CPE e CPI. Não recomendamos o uso desses cálculos em relatórios de API(saiba mais).
Eventos:
Pode obter as estatísticas de qualquer evento que tenha definido. Observe que, em vez de usar o nome do evento, conforme definido no aplicativo Singular, é necessário usar a ID gerada automaticamente do evento, que pode ser obtida no Ponto de extremidade de métricas de coorte.
Consultando dados combinados
É possível usar a API para executar uma consulta combinada de rede e rastreador, que exibe os custos da campanha e a receita ou outros KPIs de desempenho da campanha.
Esse tipo de consulta usa dimensões e métricas especiais que são baseadas em dados do rastreador e da rede, mas envolvem lógica adicional nos bastidores, conforme detalhado abaixo.
O que é que uma consulta combinada faz?
- Inclui estatísticas de rede (como o custo) e estatísticas do rastreador (como instalações e receita) na mesma consulta.
-
As dimensões inteligentes ajudam a combinar os dados da rede e do rastreador na mesma linha sempre que possível.
As dimensões "combinadas" ou "unificadas" do Singular são baseadas em dados de rede e de rastreador. Elas são processadas pelo Singular para corrigir incompatibilidades de dados comuns e garantir que você veja seus dados combinados com a maior granularidade possível.
Por exemplo, o nome de uma campanha específica no rastreador pode ser ligeiramente diferente do nome da campanha extraído da rede de anúncios. Assim, se executar um relatório do rastreador e um relatório de rede e juntar os resultados, pode obter linhas divididas para a campanha, em que uma linha tem estatísticas de rede e a outra tem estatísticas do rastreador. Mas se você executar um relatório combinado (usando a dimensão unified_campaign_name), o Singular garante que você ainda possa obter estatísticas de rede e estatísticas de rastreador na mesma linha para a campanha.
-
Métricas inteligentes e personalizáveis extraem os dados da fonte certa em cada caso.
Em situações em que a mesma estatística é oferecida tanto pela rede quanto pelo rastreador, por exemplo, o número de instalações por campanha em um determinado intervalo de datas, a métrica combinada fornece uma única fonte de verdade, escolhendo de forma inteligente a estatística do rastreador ou a estatística da rede com base no uso padrão do setor.
Por exemplo, a métrica custom_installs contém o número de instalações do rastreador, a menos que seja uma rede auto-atribuída(SAN), como Facebook ou Twitter, caso em que a estatística de rede é mais importante, e custom_installs contém a métrica de rede.
Se a escolha padrão do Singular não funcionar para o seu caso específico, você pode fazer com que o Singular reconfigure métricas específicas para você.
Observação: as métricas personalizadas não estão disponíveis para análises criativas. Selecione métricas de rede ou métricas de rastreador.
E se eu precisar saber a origem das minhas métricas?
Você pode querer saber a fonte exata de cada métrica para cada campanha - por exemplo, se estiver tentando encontrar e solucionar discrepâncias significativas entre a rede e o rastreador.
Nesse caso, você pode adicionar a métrica de rede (consulte Campos disponíveis para dados de rede) e a métrica do rastreador (consulte Campos disponíveis para dados do rastreador) ao relatório combinado. Por exemplo, extraia todas as três métricas de instalação: custom_installs, adn_installs, tracker_installs.
Dessa forma, você pode usar custom_installs como seu KPI, mas ainda ver se há uma diferença significativa entre adn_installs e tracker_installs.
Campos disponíveis para dados combinados
Consulte a página Métricas e dimensões para obter uma descrição de cada campo.
Dimensões básicas (devem estar disponíveis para todas as redes e rastreadores):
- app
- fonte
- unified_campaign_id
- nome_da_campanha_unificada
Dimensões adicionais opcionais (o suporte varia consoante a rede/rastreador):
- os
- plataforma
- campo_país
- adn_sub_adnetwork_ name
- adn_account_id
- nome_da_conta_adn
- sub_campaign_id
- nome_da_subcampanha
Repartição por palavra-chave e/ou editor (o suporte varia consoante a rede/rastreador, não pode ser obtido na mesma consulta que a repartição criativa):
- keyword_id
- palavra-chave
- publisher_id
- publisher_site_id
- nome_do_site_do_editor
Detalhamento criativo (o suporte varia de acordo com a rede, disponível apenas para usuários do serviço de atribuição da Singular):
- creative_type
- adn_creative_id
- adn_creative_name
- creative_url
- creative_image
- creative_text
- largura_da_criatividade
- altura_da_criatividade
- creative_is_video
Dimensões personalizadas:
Se você definiu dimensões personalizadas com base nessas dimensões padrão, é possível extraí-las usando suas IDs. Use o Ponto de extremidade de dimensões personalizadas para obter todas as dimensões personalizadas definidas na sua conta e suas IDs.
Métricas básicas:
- adn_cos
- adn_original_cost
- moeda original
- custom_impressions
- cliques_personalizados
- custom_installs
- tracker_conversions
- rastreador_conversões
- daily_active_users
Métricas para criativos de vídeo e campanhas baseadas em vídeo:
- video_views
- visualizações de vídeo_25pct
- visualizações_vídeo_50pct
- visualizações de vídeo_75pct
- visualizações_de_vídeo concluídas
- taxa_de_visualizações_de_vídeo_concluídas
Métricas de coorte:
- receita
- original_revenue
Para obter uma lista completa das métricas de coorte que você pode usar, consulte o Ponto de extremidade de métricas de coorte. Para obter mais informações, consulte O que são métricas de coorte?
Observe que as métricas de coorte incluem cálculos baseados em proporção, como CPE e CPI. Não recomendamos o uso desses cálculos em relatórios de API(saiba mais).
Eventos:
Pode obter as estatísticas de qualquer evento que tenha definido. Observe que, em vez de usar o nome do evento, conforme definido no aplicativo Singular, é necessário usar a ID gerada automaticamente do evento, que pode ser obtida no Ponto de extremidade de métricas de coorte.
Observações:
- O Singular tenta fornecer o nível mais alto de granularidade disponível, mas nem todas as redes e rastreadores suportam todas as divisões. Consulte Conectores de dados em detalhes para obter mais informações sobre quais dados o Singular extrai de cada fonte.
- Os relatórios combinados de nível criativo estão disponíveis apenas para usuários do serviço de atribuição da Singular.
- As métricas personalizadas não estão disponíveis para detalhamentos criativos. Selecione métricas de rede ("adn_...") ou métricas de rastreador ("tracker_...").
Resumo: que tipos de dados estão disponíveis para você?
| Eu uso o Singular para... | |||
|---|---|---|---|
| Analytics + Atribuição Singular | Somente o Analytics, mas configuro o Singular para extrair dados do meu rastreador de terceiros | Extrair dados apenas das minhas redes de anúncios | |
| Dados de rede | Disponível | Disponíveis | Disponíveis |
| Dados do rastreador | Disponível | Disponível | - |
| Campos combinados | Disponíveis | Disponível para redes de auto-atribuição (sem repartição criativa) | - |
Como consultar a API de relatórios
Depois de decidir que tipo de dados deseja consultar e de fazer uma lista das métricas e dimensões específicas em que está interessado, veja como usar a API de relatórios.
Executando uma consulta básica
| 1 |
Consulte o ponto de extremidade Criar relatório assíncrono (consulte a referência do ponto de extremidade), especificando as métricas e as dimensões escolhidas. Isso gerará uma consulta de relatório assíncrona e retornará um ID de relatório. |
| 2 |
Usando o ID do relatório, consulte o ponto de extremidade da API Get Report Status (consulte a referência do ponto de extremidade) para ver quando o relatório terminou de ser executado. Quando o relatório é concluído, o ponto de extremidade Get Report Status retorna um URL de relatório. |
| 3 |
Descarregue o relatório a partir do URL do relatório. |
Nota: Devido às grandes quantidades de dados processados pelo Singular, recomendamos filtrar cada consulta para uma única fonte (rede) ou conetor de dados e para um único dia. Por exemplo, se estiver a executar um relatório sobre as suas campanhas do Facebook nos últimos 7 dias, execute 7 relatórios separados. Isso garante que suas consultas não serão muito pesadas para serem executadas.
Executando relatórios diários
Os dados no Singular são atualizados diariamente. Normalmente, você gostaria de extrair seus dados do Singular todos os dias, incluindo:
- Dados de ontem
- Dados históricos que podem ter sido atualizados pelas suas redes.
Em seus relatórios diários regulares, recomendamos usar as seguintes janelas de tempo para extrair dados históricos:
| Tipo de consulta | Janela de tempo recomendada |
| Dados de rede | 7 dias atrás. |
| Dados do rastreador ou dados combinados | Um período tão longo quanto o período de coorte mais longo. Por exemplo, se você tiver coortes de 30 dias, consulte 30 dias atrás. Se não estiver a obter quaisquer dados de coorte, como receitas, obter 7 dias atrás é normalmente suficiente. |
Verificação da disponibilidade de dados
É possível usar o ponto de extremidade Status de disponibilidade de dados para verificar, para cada conetor de dados, se o Singular tem dados desse conetor para uma determinada data e quando foi a última vez que esses dados foram atualizados.
O uso mais comum para esse endpoint é verificar se os dados já estão disponíveis para ontem para cada um dos seus conectores de dados. Desta forma, se todos os conectores de dados estiverem prontos, pode começar a executar relatórios para todos os seus dados. Se apenas alguns dos conectores de dados tiverem dados e outros não, pode optar por esperar que todos terminem ou executar um relatório em cada fonte de dados à medida que os respectivos dados ficam disponíveis. (Para executar um relatório em um único conetor de dados em Criar relatório assíncrono, filtre o relatório por data_connector_id).
Observe que a Singular não recomenda a execução de um relatório em mais de um conetor/fonte de dados na mesma consulta.
Observação sobre "conetor de dados" vs. "fonte":
No Singular, uma "fonte" é um parceiro de rede de anúncios do qual o Singular extrai seus dados de publicidade. Um "conetor de dados" é uma ferramenta que se conecta a uma rede de anúncios e extrai dados dela.
Dependendo da sua configuração, pode ter vários conectores de dados a partilhar a mesma fonte. Isso significa que eles extraem dados para o Singular da mesma plataforma (mas com nomes de conta, configurações etc. diferentes).
O ponto de extremidade Disponibilidade de dados retorna a disponibilidade por conetor de dados em vez de por fonte. Se você usar o novo parâmetro "expanded=true" (recomendado), os resultados incluirão o parâmetro data_connector_id, que pode ser usado para filtrar seu relatório.
Dica: data_connector_id é um campo de rede. Se executar um relatório que inclua dados da rede e do localizador, incluir data_connector_id significa que os dados da rede e do localizador serão divididos em linhas separadas (consulte Juntar dados da rede e do localizador">Junir dados da rede e do localizador). Para corrigir isto, quando começar a processar os resultados na sua plataforma de BI, basta agrupar os resultados por fonte e não incluir o campo data_connector_id.
Verificar a atualidade dos dados
Para ver o quão atualizados estão os dados da sua rede no Singular, inclua a dimensão data_connector_timestamp_utc na sua consulta de relatório.
Essa dimensão inclui a data e a hora em que o Singular começou a extrair os dados do conetor de dados (independentemente de quanto tempo levou para ingerir, processar e salvar os dados no banco de dados Singular).
Exemplos de casos de uso para o carimbo de data/hora de dados incluem:
- Se você estiver enfrentando discrepâncias entre os relatórios do Singular e os dados no seu painel de rede
- Se você estiver usando destinos de dados Singular (ETL) para puxar dados do Singular para sua plataforma de BI e quiser ver se o Singular tem dados mais recentes
Dica: data_connector_id é um campo de rede. Se você executar um relatório que inclua dados de rede e de rastreador, incluir data_connector_id significa que os dados de rede e de rastreador serão divididos em linhas separadas (consulte Unindo dados de rede e de rastreador).