Abrir a adPluga dentro da sua aplicação

São dois passos. O seu servidor pede uma sessão com a chave de integração; o browser abre-a num diálogo, já autenticada. O utilizador nunca vê um ecrã de login — e é de propósito: um formulário de login dentro de uma janela de outro site é indistinguível de uma burla, e a sessão do adPluga também não viaja para lá. Por isso a autenticação fica no seu servidor, onde a chave está segura, e a janela só mostra o ecrã já pronto a usar.

• O segredo é de uso único e dura 5 minutos. Peça-o quando a pessoa carregar no botão, não no carregamento da página.
• A página só aceita ser enquadrada pela origem que declarou. Outra origem é recusada pelo browser.
• O ecrã não pode fazer mais do que a chave: os âmbitos dela mandam, e facturação, carteira, pagamentos e a gestão de chaves estão fora de alcance.

Do lado do servidor, com a chave de integração. Nunca do browser: a chave não pode sair do seu backend.

curl -X POST https://api.adpluga.com/v1/embed/sessions \
  -H 'Authorization: Bearer ak_live_•••' \
  -H 'Content-Type: application/json' \
  -d '{"component":"campaign_create","origin":"https://admin.YOUR_COMPANY.com"}'

# {
#   "client_secret": "cs_•••",
#   "url": "https://api.adpluga.com/embed/campanha/?cs=cs_•••&mode=live",
#   "expires_at": "2026-01-01T12:05:00Z"
# }

Devolva o client_secret e o url ao seu frontend. O url já leva o segredo e o ambiente.

Uma linha de script e uma chamada. O diálogo ajusta-se sozinho à altura do conteúdo e ocupa o ecrã inteiro no telemóvel.

<script src="https://cdn.adpluga.com/v1/embed.js"></script>
<script>
  async function abrir(component) {
    const r = await fetch("/api/adpluga/session", {
      method: "POST",
      body: JSON.stringify({ component }),
    });
    const s = await r.json();
    AdPlugaEmbed.open({
      url: s.url,
      clientSecret: s.client_secret,
      onDone: (r) => console.log("created", r),
      onClose: () => console.log("closed"),
    });
  }
</script>

Cada componente pede os âmbitos de que precisa. Uma chave sem eles recebe 403 ao criar a sessão, não a meio do ecrã.

campaign_create — precisa de campaign:write

O formulário completo de campanha: objectivo, modelo de preço, lance e orçamento, calendário, geografia, dispositivos e categorias. No plano gratuito explica que o lance ordena e ainda não gasta.

ad_create — precisa de campaign:read, ad:write, asset:read e asset:write

Escolhe a campanha, o tipo de criativo (imagem, HTML5, nativo, template, vídeo, rewarded, carrossel, áudio) e o formato IAB. O carregamento do ficheiro acontece dentro do diálogo e o anúncio sai para moderação.

slot_create — precisa de property:read e slot:write

O espaço onde o anúncio aparece: a propriedade a que pertence, um nome, o formato e o tamanho IAB. Uma propriedade ainda não verificada é oferecida à mesma — serve em modo de teste até o domínio ser verificado.

O diálogo fala com a sua página por postMessage. O carregador já trata do resize e do fecho; onDone entrega-lhe o que foi criado.

{ "source": "adpluga", "type": "ready" }
{ "source": "adpluga", "type": "resize", "height": 1240 }
{ "source": "adpluga", "type": "done", "entity": "campaign", "campaign_id": "…", "name": "…" }
{ "source": "adpluga", "type": "done", "entity": "ad", "ad_id": "…", "campaign_id": "…", "status": "in_review" }
{ "source": "adpluga", "type": "done", "entity": "slot", "slot_id": "…", "name": "…" }
{ "source": "adpluga", "type": "close" }

Se ligar o listener à mão, compare sempre event.origin com a origem da adPluga antes de acreditar na mensagem.

O prefixo da chave decide: uma ak_test_ escreve em modo de teste — não cobra, não consome quota, não conta para as métricas — e o diálogo diz isso na cara, com um selo e uma nota. O modo fica gravado no token que a página usa, por isso não há cabeçalho nem parâmetro que o mude.

Quem já gere campanhas do seu lado raramente tem os mesmos nomes. Esta é a correspondência que verificámos contra a API real, campo a campo.

O que fica do seu lado: desconto, cashback e pontos são mecânicas da sua promoção, não do servidor de anúncios; push, e-mail e SMS são canais seus — a adPluga entrega o banner. O identificador interno e a descrição também ficam consigo, porque não os guardamos.

• O segredo é gasto na primeira troca. Uma segunda tentativa com o mesmo segredo devolve 401.
• O token da página vive em memória e nunca é gravado em cookie nem em storage, por isso fechar o diálogo esquece-o.
• A política de enquadramento é construída por sessão: só a origem que indicou consegue mostrar a página.
• O token está preso aos âmbitos da chave. Mesmo sendo um token de sessão, é recusado em qualquer rota que a chave não abrisse.