Muitos sites, muitos anúncios e muitas estatísticas. É fácil se confundir com os dados e perder horas verificando cada código de anúncio. Adsterra Publisher API é uma solução para aqueles que precisam rastrear perfeitamente cada posicionamento de anúncio.
Com a API, os proprietários de sites economizam horas extraindo métricas como CPM, cliques ou receita. Eles usam uma tática fantástica ao utilizar um Smartlink em várias páginas! Se você também deseja melhorar sua estratégia de monetização, confira este post e obtenha dicas práticas!
What is the Adsterra Publisher API?
API — the acronym for Application Programming Interface — is a means of communication between applications. Rephrasing this, API requests data from Adsterra and displays it in a publisher’s application or platform.
Publishers automate monetization tasks by only telling Adsterra to send the correct data to the right place in the correct order and at the correct frequency. You keep control over the core metrics across all domains.
To make it all happen, you need to know how to call out to the API and how to make it pull the stats. So let’s dive into some tech stuff and find out which datasets you can get.
Dados que você pode recuperar com a API
- Sites que você adicionou ao Adsterra, incluindo seus nomes e IDs únicos.
- Posicionamentos de anúncios em cada site adicionado à sua conta.
- Uma lista de posicionamentos em todos os sites.
- Uma lista dos seus Smartlinks com relatórios de estatísticas atuais e métricas de desempenho.
- Um relatório contendo as seguintes métricas: impressões, cliques, CTR, CPM e receita por data.
- Você também pode especificar um domain_id, placement_id e placement_sub_id, datas de início e término, bem como um GEO específico.
Por enquanto, a Adsterra Publishers API oferece suporte apenas ao método GET. Isso significa que você pode obter os dados sem alterar sua estrutura ou quantidade.
How to apply API: Top use cases from publishers
These are not only CPM rates you can monitor regularly. Let’s explore how publishers automate their business with the Adsterra Publisher API. Here are some of the popular use cases:
1. Control how every ad placement performs
Imagine you run 20 websites with 40 ad placements (Popunders and Banners). You add one more Banner on a main page of one of these sites. With API, you can get critical stats, grouping them by placements inside every domain: impressions, clicks, CTR, and revenue.
We’ll lay out a more detailed example for this case in the Practice chapter.
2. Check best-performing countries to add more traffic
Group stats by country to catch which geos deliver the highest revenue on every website.
Grouping filters will help you out when you need to focus on dates, domains, and placements, as well.
3. Posicione e gerencie múltiplos Smartlinks fora do Adsterra
Muitos editores monetizam sites de várias páginas, colocando Smartlinks em todas as páginas. Eles precisam gerar um código único para cada página para obter estatísticas corretas. Mas com o Adsterra Publisher API, você pode facilmente criar um código único. Basta adicionar um placement_sub_id como parâmetro a qualquer uma de suas URLs.
Outra oportunidade é recuperar uma lista de todos os seus Smartlinks via solicitação GET para gerenciá-los e coletar estatísticas sem fazer login no Adsterra ou contatar o suporte.
Smartlink é uma URL simples que você coloca dentro do conteúdo. Parece um hiperlink. Cada clique do usuário abre um novo anúncio. Um parâmetro placement_sub_id fará com que uma URL obtida do Adsterra seja única e fácil de rastrear.
Começando com a Adsterra Publisher API
Nossa API é gratuita e qualquer editor pode se beneficiar dela. Para acessar todos os nossos recursos, siga esta breve instrução:
- Para enviar solicitações de API, primeiro, registre-se como editor do Adsterra.
- Adicione um site com qualquer uma das seguintes unidades de anúncio: Popunder, Social Bar, Banner Nativo, Banner ou Smartlink.
Confira o guia para adicionar sites e gerar códigos de anúncios se você é novo no Adsterra.
Se você já operou sites no Adsterra, pule esta parte e avance.
- O site e as unidades de anúncio que você irá rastrear via API devem estar Ativos.
- Navigate the API page from your account and hit the GENERATE NEW TOKEN button.
Save this token. You will then add to an API request, connecting your platform with your Adsterra publisher’s account. In the following chapter, we’ll learn how to create such requests.
API requests basics
When you request data, you address the Adsterra server:
https://api3.adsterratools.com/publisher
Every request contains:
- A unique token you generate on your Adsterra account (see the previous chapter). It’s also called the API Key.
- Parameters, or which data you want Adsterra to return.
- Format (JSON, CSV, XML)
Here is an example of a request in PHP where we request a full list of websites (domains) added to Adsterra. We request the CSV format and place the X-API-Key (or token) in the Header part:
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api3.adsterratools.com/publisher/domains.csv', [
'headers' => [
'Accept' => 'application/json',
'X-API-Key' => '123',
],
]);
echo $response->getBody();Prática: Solicitações Comuns de API
Vamos agora passar por alguns exemplos de solicitações comuns que os editores enviam ao nosso servidor. Para tornar todos os nossos exemplos mais ilustrativos, veremos como a recuperação de dados se parece na vida real.
Você pode pular para a documentação da Adsterra e testar várias solicitações. Agora você precisará colar a chave da API (ou token) obtida anteriormente no campo apropriado:
1. Agrupamento de estatísticas por posicionamento de anúncios
Lembra-se de um dos casos de uso para controlar o desempenho de todos os posicionamentos? Vamos examiná-lo em mais detalhes. Vá para a página Get Statistics da documentação do Adsterra Publisher API. Aqui, você pode verificar todos os parâmetros para modificar a resposta final. Inclua domain ID e placement ID na sua solicitação, e finalmente, escolha a opção group_by placement.
The request you send to Adsterra may look like this (PHP):
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api3.adsterratools.com/publisher/stats.json??domain=domain_id&placement=placement_id&start_date=2022-03-06&finish_date=2022-03-06&group_by=placement&country=country', [
'headers' => [
'Accept' => 'application/json',
'X-API-Key' => '123',
],
]);
echo $response->getBody();The same request when using JavaScript Fetch:
const settings = {
async: true,
crossDomain: true,
url: 'https://api3.adsterratools.com/publisher/stats.json?domain=domain_id&placement=placement_id&start_date=2022-03-06&finish_date=2022-03-06&group_by=placement&country=country',
method: 'GET',
headers: {
Accept: 'application/json',
'X-API-Key': '123'
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
2. Grouping stats by country
You can pull stats reports, grouping core metrics by country, in almost the same way we’ve just done. Include the group_by=country query parameter in your request.
Here’s how the final request may look like if sent in PHP:
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api3.adsterratools.com/publisher/stats.json?domain=domain_id&placement=placement_id&start_date=2022-03-06&finish_date=2022-03-06&group_by=country&country=country', [
'headers' => [
'Accept' => 'application/json',
'X-API-Key' => '123',
],
]);
echo $response->getBody();The same request for JavaScript Fetch:
const settings = {
async: true,
crossDomain: true,
url: 'https://api3.adsterratools.com/publisher/stats.json?domain=domain_id&placement=placement_id&start_date=2022-03-06&finish_date=2022-03-06&group_by=country&country=country',
method: 'GET',
headers: {
Accept: 'application/json',
'X-API-Key': '123'
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
3. Colocação de um Smartlink em várias páginas do site
A API permite que você adicione um parâmetro único a um URL de Smartlink. Você precisa anexar um placement_sub_id ao URL. Aqui está um guia passo a passo.
O parâmetro Sub ID
Um parâmetro Sub ID é um identificador único que você adiciona a um link de URL. A estrutura do URL não muda, apenas um novo parâmetro é adicionado. O Sub ID permite rastrear o desempenho do mesmo Smartlink colocado em diferentes sites ou páginas.
Onde colocar o parâmetro Sub ID?
Coloque o &psid=sub_id_1 no final do seu link URL do Smartlink, onde sub_id_1 é o seu identificador único. Componha-o usando letras, números ou ambos.
Como usar o Sub ID em solicitações da Publisher API
Aqui está um exemplo de uma consulta para obter estatísticas agrupadas pelo parâmetro Sub ID:
1. Adicione Sub ID ao URL:
- Anexe &psid=sub_id_1 ao seu URL.
- Certifique-se de que sub_id_1 seja um identificador único.
Exemplo em Ruby:
https://yourdomain.com/path/to/ad?psid=home_page_1
2. Coloque um Smartlink com Sub ID em uma página da web
3. Certifique-se de ter gerado diferentes Sub IDs para cada página
Exemplos:
- Página inicial: &psid=home_page_1
- Página sobre: &psid=about_page_2
- Página de contato: &psid=contact_page_3
4. Obtenha estatísticas:
- Use a Adsterra Publisher API para obter as estatísticas que você precisa.
- Agrupe os resultados pelo parâmetro placement_sub_id para ver o desempenho por localização.
Exemplo de Consulta API (cURL):
curl --request GET \ --url 'https://api3.adsterratools.com/publisher/stats.json?domain=8356709&placement=28948612&start_date=2024-07-09&finish_date=2024-07-09&group_by%5B%5D=placement_sub_id' \ --header 'Accept: application/json' \ --header 'X-API-Key: {api_token}' Finishing up with practice, we encourage you to take a closer look at all Adsterra monetization ad formats. Choose the most beneficial for your business and target audience and start earning with or without API.
API requests errors
When everything works fine, you will get a 200 server response, which means “Success.” However, sometimes pitfalls occur. So here are the most common errors and their meanings. Use those tips to deal with them yourself or ask for help from our support team.
- 401 — the token is incorrect. Please use the token from your account (see the API tab)
- 403 — the token is no longer valid. Please generate a new token
- 404 — not found. Make sure the URL is correct
- 405 – not allowed
- 422 – the server can’t interpret the instructions, however, the syntax is correct
Summarizing the benefits
Even a slight CPM change may affect your monetization strategy. With Adsterra Publishers API, you can automatically fetch important metrics from your account without building another report or exporting a CSV file.
These are some tangible benefits you can enjoy:
- Monitor the key metrics and update them automatically.
- Compare the efficiency of Adsterra ad formats for publishers.
- Save plenty of time on building dynamic reports and collecting stats for specific periods.
- Control your core metrics — CPM and revenue — and react faster than ever.
But enough theory. It’s time to make the most of Adsterra Publishers API 