adPluga

Guia de integração

Do seu admin de promoções para a adPluga

Se já gere campanhas e banners do seu lado, este é o percurso completo pela API — na ordem em que o faria, com os mesmos nomes que usa.

A forma da coisa

A adPluga separa três coisas que o seu admin junta num ecrã só. Vale a pena tê-las claras antes do primeiro pedido.

  • A campanha guarda o que é comercial: objectivo, preço, período e a quem se dirige. Não tem imagem.
  • O anúncio é o criativo dentro de uma campanha: a imagem, o destino do clique e o texto alternativo. Herda o período da campanha.
  • O espaço é a posição onde o anúncio aparece na sua app. É o que a app pede pelo nome — não é um campo do banner.

1. A chave de integração

Crie-a no painel, em Definições › Chaves. Marque só os âmbitos deste percurso: a chave não alcança mais nada, e facturação, carteira e pagamentos ficam fora do alcance por construção. O segredo aparece uma vez.

# Definições › Chaves › Nova chave de integração
# Âmbitos para este percurso:
#   campaign:read  campaign:write
#   ad:write       asset:read  asset:write
#   audience:read  audience:write
#   property:read  slot:read   slot:write

export ADPLUGA_KEY=ak_test_•••   # ak_live_ quando passar a produção

2. Os espaços, um por posição

As suas quatro posições — home topo, home meio, categoria e pesquisa — são quatro espaços. Crie-os uma vez; depois é a campanha que escolhe onde aparece.

# Uma propriedade por app/site, um espaço por posição.
curl -X POST https://api.adpluga.com/v1/slots \
  -H "Authorization: Bearer $ADPLUGA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "property_id": "PROPERTY_ID",
    "name": "home-topo",
    "format": "display",
    "width": 1200, "height": 400,
    "accepted_sizes": [{"w":1200,"h":400}]
  }'

# Repita para home-meio, categoria e pesquisa.
# O nome é identificador: /serve aceita o id ou o nome, dentro da propriedade.

O tamanho é livre: 1200×400, 800×400 e 600×600 são aceites tal como estão. Não precisa de se limitar a tamanhos IAB.

3. As audiências

Clientes VIP, sem compra há 30 dias, novo registo: cada uma é uma audiência que cria uma vez e alimenta a partir do seu CRM. Envie identificadores já em hash — não precisamos de saber quem são.

# A "Audiência Alvo" do seu admin é uma audiência first-party.
curl -X POST https://api.adpluga.com/v1/audiences \
  -H "Authorization: Bearer $ADPLUGA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Clientes VIP", "key": "vip"}'

# Depois empurre os membros a partir do seu CRM.
curl -X POST https://api.adpluga.com/v1/audiences/AUDIENCE_ID/members \
  -H "Authorization: Bearer $ADPLUGA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"subjects": ["HASH_DO_CLIENTE", "..."]}'

4. A campanha

É aqui que entra tudo o que no seu admin é comercial. O Idempotency-Key pode ser o seu identificador interno: repetir o pedido com a mesma chave devolve a mesma campanha em vez de criar outra.

curl -X POST https://api.adpluga.com/v1/campaigns \
  -H "Authorization: Bearer $ADPLUGA_KEY" \
  -H 'Idempotency-Key: promo-verao-2026' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Promo Verão 2026",
    "objective": "traffic",
    "pricing_model": "CPM",
    "bid_cents": 500,
    "pacing": "uniforme",
    "currency": "AOA",
    "starts_at": "2026-10-01T09:00:00Z",
    "ends_at":   "2026-10-31T23:59:00Z",
    "targeting": {
      "geo": ["AO"],
      "device": ["mobile"],
      "slots": ["home-topo"],
      "audiences": { "first_party_include": ["vip"] },
      "freq_cap": { "per_user_per_day": 3 }
    }
  }'

A prioridade do seu admin é o lance: o leilão ordena por eCPM, portanto Alta é simplesmente um bid_cents maior. O limite de utilizações mapeia para freq_cap por pessoa e por dia; para um tecto absoluto use budget_total_cents.

5. O criativo

Duas chamadas: uma pede o destino de upload, a outra confirma quando o ficheiro chegou. O URL que fica é o que se usa no banner.

# 1. Peça um destino de upload
curl -X POST https://api.adpluga.com/v1/assets/presign \
  -H "Authorization: Bearer $ADPLUGA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"filename":"banner.png","mime":"image/png","size_bytes":184320}'

# 2. Envie o ficheiro para o upload_url devolvido (PUT), depois confirme
curl -X POST https://api.adpluga.com/v1/assets/ASSET_ID/commit \
  -H "Authorization: Bearer $ADPLUGA_KEY"

7. Ver o anúncio a responder

A app pede o anúncio ao plano de dados com a chave publicável da propriedade. É a mesma chamada que os nossos SDKs fazem por baixo.

# A app pede o anúncio com a chave publicável da propriedade.
curl 'https://edge.adpluga.com/v1/serve?slot=home-topo' \
  -H 'X-AdPluga-Key: pk_test_•••'

# A resposta traz o criativo, o alt_text e os URLs de medição já assinados.
# Enquanto estiver a desenvolver, use ak_test_ e pk_test_: nada é cobrado.

E as lojas?

A sua lista de lojas não tem equivalente directo, e isso é deliberado — nós não sabemos o que é uma loja sua. Há dois caminhos: se cada loja tem o seu espaço na app, crie um espaço por loja e aponte a campanha aos espaços dessa loja; se as lojas partilham as mesmas posições, faça de cada conjunto de clientes uma audiência e segmente por aí. O primeiro caminho é por inventário, o segundo por pessoas.

O que é nosso e o que continua seu

A adPluga é o servidor de anúncios. Isso deixa de fora, de propósito, boa parte do que o seu admin faz:

  • Desconto, cashback e pontos são a mecânica da sua promoção. Nós entregamos o banner que a anuncia; o resgate é seu.
  • Push, e-mail e SMS são canais seus. Nós servimos o banner na app.
  • O identificador interno e a descrição ficam consigo — não os guardamos. Use o identificador como Idempotency-Key e fica com a ligação feita.
  • Enquanto desenvolve, use chaves de teste: escrevem em modo de teste, não cobram, não consomem quota e não contam para as métricas.