SDKs e bibliotecas

Os quatro SDKs de cliente expõem o mesmo formato: inicializa uma vez com uma chave publicável e renderiza um slot. Quem chama server-to-server pode saltar o SDK e ir directo ao REST do edge.

• Webv0.4.0
• Flutterv0.4.0
• Androidv0.4.0
• iOSv0.4.0

Vem como custom element nativo (<adpluga-ad>) e como módulo ES para controlo total. Lazy load com IntersectionObserver, beacon de impressão single-fire, tracker de clique com redirect assinado. Zero dependências em runtime.

Instalação

npm install @adpluga/web@0.4.0

Uso mínimo

<script type="module" src="https://cdn.adpluga.com/v1/adpluga.js"></script>

<adpluga-ad
  publisher-key="pk_test_•••"
  slot-id="slot_home_top"
  format="banner_300x250"
  lazy></adpluga-ad>

• •Agnóstico ao framework — funciona com React, Vue, Svelte, Astro, HTML puro.
• •Faz lazy load via IntersectionObserver; só pede quando o slot entra no viewport.
• •Impressão dispara uma vez por instância do elemento; o clique usa o redirect assinado do edge.
• •Módulo ES tipado (initialize, serve, track) quando precisas de render à medida.

Widget AdPlugaBanner para o caso comum; primitivas AdPlugaVideo e AdPlugaHtml de baixo nível quando precisas de compor o teu próprio render. Consent, logger e stream de erros são todos APIs top-level.

Instalação

dependencies:
  adpluga_flutter: ^0.4.0

Uso mínimo

import 'package:flutter/material.dart';
import 'package:adpluga_flutter/adpluga_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AdPluga.initialize(publisherKey: 'pk_test_•••');
  runApp(const MyApp());
}

• •AdPlugaBanner cobre o render standard de slot com callbacks de impressão/clique/erro.
• •Hierarquia sealed AdPlugaError — usa pattern matching em vez de fazer parse a strings.
• •setLoggerEnabled/setLoggerSink ao nível do pacote para debug estruturado.
• •Estado de consentimento (LGPD/GDPR/COPPA) reencaminhado a cada chamada de serve automaticamente.

AdView com uma única chamada load(slotId, format?, listener?). AdPluga.initialize recebe só a chave publicável — não pede Context. Stream de eventos via sealed class SdkEvent; debug via AdPlugaLogger.enabled.

Instalação

dependencies {
  implementation("com.adpluga:adpluga:0.4.0")
}

Uso mínimo

class AdPlugaApp : Application() {
  override fun onCreate() {
    super.onCreate()
    AdPluga.initialize(publisherKey = "pk_test_•••")
  }
}

• •Init de uma linha: AdPluga.initialize(publisherKey = "pk_...").
• •AdView.load reporta Impression, Click e Error via AdListener.
• •Coroutine-friendly — cada entrada do SDK suspende sem bloquear a UI thread.
• •AdPlugaLogger.enabled = true imprime eventos de ciclo de vida estruturados sob a tag AdPluga.

AdPluga.initialize é throwing; AdPlugaView(frame:) + load(slotId:format:) monta um banner. Os métodos do delegate usam a convenção do view com underscore. Envolve AdPlugaView num UIViewRepresentable para SwiftUI.

Instalação

dependencies: [
  .package(
    url: "https://github.com/adpluga/adpluga-ios.git",
    from: "0.4.0"
  ),
]

Uso mínimo

import AdPluga

func application(
  _ app: UIApplication,
  didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
  _ = try? AdPluga.initialize(publisherKey: "pk_test_•••")
  return true
}

• •Init throwing apanha chaves malformadas no arranque em vez de no primeiro render.
• •AdPlugaViewDelegate reporta willPresent, didLoad, didClick e didFail(_:error:).
• •Sendable-friendly — seguro chamar load(slotId:) a partir de qualquer actor.
• •AdPlugaLogger.enabled = true faz stream de eventos os_log para o Instruments.

Salta o SDK quando renderizas do lado do servidor (HTML de email, backends de apps nativas, AMP, CTV). Chama o edge directamente com uma chave publicável — o mesmo contrato que os SDKs de cliente usam por baixo. 204 significa sem fill; trata como no-ad, não como erro.

curl "https://edge.adpluga.com/v1/serve?slot=slot_home_top" \
  -H "X-AdPluga-Key: pk_live_•••"

• •Sem estado — GET /v1/serve, sem cookies de sessão, sem preflight CORS.
• •204 No Content em fills vazios — nunca devolve um placeholder inventado.
• •impression_url / click_url assinados — seguro embeber em páginas de terceiros.
• •Endpoints só de servidor (/v1/audio/stitch, /v1/email/prepare) usam sk_ via Authorization: Bearer.

Todos os endpoints estão documentados em api/openapi.yaml. Gera um cliente tipado com openapi-generator ou orval — a spec é validada a cada release e corresponde à produção 1:1.