Pixora Ads SDK e API para desenvolvedores

Selecione formatos ao registrar sua propriedade para moderação. Imagens e vídeos são tipos criativos; nativo, intersticial e recompensado são cenários de entrega. Não existe um método showVideo() separado: o servidor seleciona um criativo correspondente.

Mini App a publicidade fica dentro da interface do parceiro. A navegação do anunciante é opcional; descartar o anúncio retorna à sua tela. Os bots usam anúncios de conversação pagos por clique; canais usam postagens com CPM ou CPC. O CTA leva ao anunciante. Este JavaScript SDK é para Mini Apps, não para mensagens.

A receita do editor e os bônus dos espectadores são separados. Use nativo ou intersticial para monetizar sem recompensas. As impressões comuns exigem pelo menos 50% de visibilidade criativa por um segundo contínuo em uma janela ativa e reprodução real do vídeo. O servidor verifica a elegibilidade, limites e orçamento antes de confirmar a entrega.

Para novas integrações use SDK 1.8.4: init() e um método show explícito. O legado create()/mount() permanece compatível.

1. Abra Monetização → Propriedades → Conecte uma propriedade e escolha Mini App, bot ou canal público.
2. Forneça um nome, Telegram URL e uma descrição do tópico e do público. Para Mini Apps use o link do bot ou um link direto t.me/bot/appname. Selecione nativo, intersticial e/ou premiado antes da moderação. Descreva o posicionamento do anúncio na descrição; não há campo separado.
3. Verifique o controle: token de bot para bots/Mini Apps; permissões de administrador para canais. O token verifica o controle do bot; um moderador analisa o posicionamento.
4. Para Mini Apps e bots, crie uma chave API após aprovação e mantenha-a no servidor. A postagem automática no canal não precisa de servidor separado ou chave API: salve as configurações de postagem e verifique as permissões do bot.
5. Execute o teste abaixo, conecte seu backend e SDK ou prepare um anúncio no painel. Os anúncios ao vivo exigem uma propriedade ativa e uma demanda correspondente; a conexão não garante preenchimento de anúncios ou receita.

A demonstração @pixorAds_networkbot mostra a jornada completa do usuário: abrindo um Mini App, solicitando um anúncio através de um servidor e mostrando o formato escolhido dentro do Mini App. Você pode tentar antes de conectar sua própria propriedade.

1. Abra o bot e inicie seu Mini App. O back-end de demonstração verifica a sessão Telegram por meio de /api/v1/ad-network/demo/session.
2. O SDK chama /api/v1/ad-network/demo/offer na mesma origem. A chave secreta do editor permanece no servidor.
3. Se não houver oferta paga correspondente, o aplicativo de demonstração mostrará um vídeo introdutório. Este é o próprio estado vazio do editor, não uma visualização de anúncio: ele não gera cobrança, recompensa ou receita do editor.

1// Demo only: run after loading pixorads-publisher.v1.8.4.js inside Telegram.2const session = await fetch("/api/v1/ad-network/demo/session", {3  method: "POST",4  credentials: "same-origin",5  headers: { "Content-Type": "application/json" },6  body: JSON.stringify({ init_data: window.Telegram.WebApp.initData })7});8if (!session.ok) throw new Error("Telegram session could not be verified");9const { csrf_token, publisher_id } = await session.json();10const placement = window.PixorAdsPublisher.init({11  element: document.getElementById("pixorads"),12  endpoint: "/api/v1/ad-network/demo/offer",13  csrfToken: csrf_token,14  publisherId: publisher_id,15  language: "pt"16});17await placement.showNative();

Carregue o script uma vez em HTML. Defina o endpoint para seu próprio back-end na mesma origem. Nunca exponha a chave API ao navegador. Antes de init(), envie Telegram.WebApp.initData para seu backend: verifique sua assinatura e idade, crie uma sessão e, para autenticação de cookie, retorne um token CSRF para a opção csrfToken. Copie o publisherId público do cartão de propriedade. Os exemplos abaixo são anúncios nativos sem recompensas; consulte Mostrar métodos para outros cenários. Passe o token CSRF da sessão como um suporte React e destroy() na desmontagem.

1<!-- Render this page AFTER your backend verifies the Telegram session. -->2<!-- Your backend inserts its session CSRF token into this meta tag. -->3<meta name="csrf-token" content="YOUR_SESSION_CSRF_TOKEN">4<script src="https://pixora-ads.com/sdk/pixorads-publisher.v1.8.4.js"></script>5<div id="pixorads"></div>6<script type="module">7  const placement = window.PixorAdsPublisher.init({8    element: document.getElementById("pixorads"),9    endpoint: "/api/pixorads/offer",10    csrfToken: document.querySelector('meta[name="csrf-token"]').content,11    publisherId: "YOUR_PUBLIC_MINIAPP_PUBLISHER_ID",12    trackAudience: false,13    personalized: false,14    language: "en"15  });16  const state = await placement.showNative();17  if (state.status === "error") console.warn(state.code);18  // empty: no ad available. Continue the app; do not retry in a loop.19  // On screen removal: placement.destroy();20</script>

Escolha um exemplo abaixo. Carregue o SDK e faça com que seu back-end verifique a sessão Telegram primeiro. Substitua publisherId pelo seu ID de propriedade pública. csrfTokenFromYourSession é o token CSRF da sua sessão, não uma chave API. /api/pixorads/offer é uma rota que você implementa em seu backend.

1// Prerequisites: SDK loaded, your session verified, <div id="ad-slot"></div>.2const ads = window.PixorAdsPublisher.init({3  publisherId: "YOUR_PUBLIC_MINIAPP_PUBLISHER_ID",4  endpoint: "/api/pixorads/offer",5  csrfToken: csrfTokenFromYourSession,6  element: document.getElementById("ad-slot"),7  language: "en",8  trackAudience: false, // Enable explicitly if you measure app activity.9  personalized: false10});1112const state = await ads.showNative();13if (state.status === "empty") {14  // No matching ad. Continue your app normally; try later.15} else if (state.status === "error") {16  console.warn("Ad unavailable:", state.code);17}18// ready means rendered, NOT a paid impression.19// Keep ads alive while the card is visible.20// When removing this screen: ads.destroy();

Resultados do método

1{2  shown: true,              // Viewer handshake completed; NOT proof of payment3  completed: false,         // true only for completed rewarded viewing4  impression_confirmed: true // Ordinary viewer confirmation, when available5  // receipt, session_id: present when supplied by the viewer6  // test:true => {shown:false, completed:false, test:true}; no overlay or payout7}

Apenas um visualizador de anúncios pode ser aberto por vez. Não execute showNative() e um método de tela inteira simultaneamente em um controlador. Continue seu aplicativo em no_fill; nunca substitua uma recompensa prometida por um anúncio comum. Destrua o controlador quando sua tela for removida, não imediatamente após renderizar uma carta.

Nativo e intersticial não precisam de integração de recompensa. No modo recompensado Pixora Ads verifica a visualização; seu back-end concede moedas, vidas ou outros bônus adicionais dentro do seu aplicativo.

1. Leia o recibo opaco de showRewarded() após a demissão. É uma prova a ser verificada, não um valor de recompensa.
2. Envie-o para seu back-end autenticado. Verifique-o usando a chave desta propriedade e combine telegram_id com seu próprio usuário de sessão.
3. Em uma transação, salve o recibo_id exclusivo e conceda o bônus configurado pelo servidor. Solicitações repetidas devem retornar o resultado existente sem conceder duas vezes.

1// Inside YOUR authenticated, CSRF-protected reward route.2// req.user.telegramId must come from a verified session, never the request body.3const response = await fetch("https://pixora-ads.com/api/v1/ad-network/publisher-api/reward/verify", {4  method: "POST",5  headers: {"Content-Type": "application/json", "X-PixorAds-Key": process.env.PIXORADS_PUBLISHER_KEY},6  body: JSON.stringify({receipt: req.body.receipt}),7  signal: AbortSignal.timeout(8000)8});9if (!response.ok) throw new Error("Reward not verified");10const proof = await response.json();11if (!proof.rewarded || String(proof.telegram_id) !== String(req.user.telegramId)) {12  throw new Error("Wrong viewer");13}14// YOUR database transaction (required; not implemented by this snippet):15// 1. Insert (receipt_id, your_user_id) into a ledger with UNIQUE(receipt_id).16// 2. On a new row, grant YOUR server-configured internal bonus.17// 3. On duplicate, return the existing result for the same user.18// Commit both operations together, then return 2xx to the browser.19// Never take a reward amount from req.body or credit proof.reward as app coins.

Resposta: recompensado, recibo_id, sessão_id, editor_id, telegrama_id, operação_id, recompensa, moeda, concluído_at. Os recibos duram sete dias e são vinculados à propriedade. A verificação não transfere dinheiro. Se o seu back-end não estiver disponível, tente novamente o mesmo recebimento em vez de exigir outra visualização do anúncio.

Quando usar onReward

onReward({receipt, session_id}) é acionado após a conclusão, enquanto o visualizador pode permanecer aberto. É uma alternativa ao processamento do recibo após a demissão. O SDK não aguarda nem tenta novamente seu retorno de chamada assíncrono: implemente erros e tente novamente. Se você usar os dois caminhos, a desduplicação do servidor por recibo_id será essencial. Notificações onEvent e cliques de CTA nunca autorizam um bônus.

API valores são unidades inteiras menores: XTR / 1000 = Estrelas; RUB / 1000 = rublos; USD / 1.000.000 = dólares. recompensa:70 com moeda:XTR significa 0,07 estrelas. Em uma oferta, viewer_reward/viewer_currency descreve a recompensa do visualizador; recompensa e publisher_amount usam a moeda da campanha. publisher_income estima USD ganhos, fixados na confirmação. Nenhum deles define o número de moedas em seu aplicativo.

Seu back-end autentica o usuário, limita as solicitações e solicita um anúncio de Pixora Ads. Encaminhe a resposta JSON para o widget. Reutilize uma Chave de Idempotência para novas tentativas da mesma solicitação lógica; use uma nova chave para uma nova oferta.

1curl https://pixora-ads.com/api/v1/ad-network/publisher-api/offer \2  -H "X-PixorAds-Key: $PIXORADS_PUBLISHER_KEY" \3  -H "Idempotency-Key: unique-logical-request-id" \4  -H "Content-Type: application/json" \5  -d '{"language":"en","format":"native"}'

1// Node.js 22+ / Express. Keep this code on YOUR SERVER.2// app, requireYourSession, verifyYourCsrf and yourRateLimit3// belong to your app. Implement them before exposing the route.4import { randomUUID } from "node:crypto";56app.post("/api/pixorads/offer", requireYourSession,7  verifyYourCsrf, yourRateLimit, async (req, res) => {8    res.set("Cache-Control", "no-store");9    const language = req.body?.language ?? "en";10    const context_token = req.body?.context_token ?? "";11    const excluded_campaigns = req.body?.excluded_campaigns ?? [];12    const excluded_frequency_groups = req.body?.excluded_frequency_groups ?? [];13    // Legacy create().mount() omits format; preserve the API's auto default.14    const format = req.body?.format ?? "auto";15    if (!["ru", "en"].includes(language)) return res.status(400).json({error:{code:"invalid_language"}});16    if (typeof context_token !== "string" || context_token.length > 2048) return res.status(400).json({error:{code:"invalid_viewer_context"}});17    if (!["auto", "native", "interstitial", "rewarded"].includes(format)) return res.status(400).json({error:{code:"invalid_format"}});18    const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;19    if (![excluded_campaigns, excluded_frequency_groups].every(ids => Array.isArray(ids) && ids.length <= 100 && ids.every(id => typeof id === "string" && uuid.test(id)))) return res.status(400).json({error:{code:"invalid_exclusions"}});20    // Reuse this ID only when retrying the SAME body upstream. SDK fallback21    // attempts carry distinct keys and narrowing-only frequency hints.22    const requestId = req.get("Idempotency-Key") || randomUUID();23    if (!/^[A-Za-z0-9:_-]{1,80}$/.test(requestId)) return res.status(400).json({error:{code:"invalid_idempotency_key"}});24    try {25      const response = await fetch(26        "https://pixora-ads.com/api/v1/ad-network/publisher-api/offer",27        {28          method: "POST",29          headers: {30            "Content-Type": "application/json",31            "X-PixorAds-Key": process.env.PIXORADS_PUBLISHER_KEY,32            "Idempotency-Key": requestId33          },34          body: JSON.stringify({ language, context_token, format, excluded_campaigns, excluded_frequency_groups }),35          signal: AbortSignal.timeout(8000)36        }37      );38      const retryAfter = response.headers.get("Retry-After");39      if (retryAfter) res.set("Retry-After", retryAfter);40      const payload = await response.json();41      // Preserve structured error.code so the SDK can show useful diagnostics.42      res.status(response.status).json(payload);43    } catch {44      res.status(503).json({ error: { code: "upstream_unavailable" } });45    }46  });

Girar ou revogar uma chave desativa ela e seus links de posicionamento. Atualize sua variável de ambiente e crie novas veiculações. As sessões iniciadas mantêm seus termos, mas as novas ações do visualizador verificam o status atual e a versão da chave.

O principal formato do bot é um anúncio após uma resposta útil, pago por visita confirmada. Os tokens BotFather permanecem no servidor proprietário; os espectadores não precisam de registro separado.

Configure a entrega, aprove criativos e visualize taxas e ganhos no cartão de propriedade do bot em Anúncios de conversa. A visualização premiada continua sendo um formato opcional com integração própria.

Adicione um canal público com sua conta e o bot Pixora Ads como administradores. Após a moderação, verifique as permissões de postagem e exclusão. Escolha visualizações (CPM, padrão) ou cliques confirmados (CPC) nas configurações do canal. Defina ganhos mínimos e limite de resultados por postagem. Publicação e aprovação automáticas estão disponíveis para ambos.

CPM paga Telegram contra-visualizações nas primeiras 24 horas, incluindo encaminhamentos; este não é um alcance ou conclusão único. CPC paga navegação confirmada em página curta sem cadastro. Visualizações, pré-visualizações e repetições para o mesmo anunciante em canais dentro de 24 horas são gratuitas. Uma impressão digital de IP e de agente de usuário não é prova de uma pessoa única. Os leitores não recebem recompensa.

A liquidação segue a colocação de 24 horas e, em seguida, a suspensão da campanha. O histórico de postagens mostra ganhos, visualizações pagas ou cliques e datas de lançamento. Os preços e ações do canal são independentes de Mini Apps; as taxas atuais aparecem nos ganhos imobiliários.

1// Load /sdk/pixorads-offerwall.v1.3.3.js first.2const demo = new PixorAdsOfferwall.DemoClient();3const { items } = await demo.catalog();4const attempt = await demo.start(items[0].id, "demo-1");5await demo.check(attempt.id); // demo_completed; paid=false; no receipt6demo.reset();

Offerwall 1.3 · Conexão, sandbox não financeira, bônus e diagnósticos em um único painel.

Um catálogo de tarefas: uma tela hospedada, componente Mini App e API para sua própria interface ou bot Telegram. Assinaturas de canais públicos e participações em grupos são suportadas. Pixora Ads deve ser administrador do chat de destino. Os primeiros lançamentos de bot e ações Mini App confirmadas pelo anunciante também são suportados após um teste de integração. São suportadas reações de grupos públicos, enquetes Pixora Ads não anônimas, novos aumentos de Premium, visitas a sites, navegação e tarefas de relatórios, incluindo pesquisa de produtos. A disponibilidade do site depende das configurações do serviço. Formatos de compra dedicados e tarefas de várias etapas não são suportados.

1. Prepare seu imóvel

Adicione e verifique uma propriedade em Minhas propriedades e conclua a moderação. Em Tarefas e recompensas escolha o modo de recompensa, configure retornos de chamada e habilite tarefas. Somente campanhas cujos anunciantes ativaram explicitamente a distribuição por parceiros são qualificadas.

• Pixora Ads recompensa: um usuário cadastrado ganha dinheiro; a propriedade ganha uma parte da taxa de plataforma. Participação inicial: 50% da taxa.
• Recompensa de propriedade: você concede moedas ou acesso; sua propriedade ganha uma parte do preço resultante. Participação inicial: 80%. Seu servidor oferece recompensas internas.

Os compartilhamentos são configuráveis e congelados quando uma tarefa é iniciada. Os rendimentos de propriedade são registados em USD a uma taxa de câmbio congelada e mantidos após verificação final (24 horas por defeito). A retenção de associados é mostrada separadamente. Uma ação confirmada não significa que a renda possa ser retirada imediatamente.

As recompensas por indicação de tarefas são financiadas pela parcela da plataforma restante após a divisão do editor. Eles não reduzem a recompensa acordada do usuário ou a renda de propriedade.

2. Escolha uma integração

Antes de habilitar tarefas, abra Monetização → Offerwall → Conexão. Salve as configurações, crie uma tarefa de exemplo e conclua-a. Seu evento possui test=true, user_id=null e zero rendimento monetário. Nunca dê crédito a um usuário real por isso. Repita o teste após alterar as configurações.

Com webhooks, o teste é enviado para a URL salva com a assinatura HMAC usual. Caso contrário, busque GET /publisher-api/tests. Seu servidor reconhece isso por meio de POST /publisher-api/tests/{conversion_id}/ack com X-PixorAds-Key. O HTTP 2xx por si só não confirma uma recompensa. Os eventos de teste permanecem disponíveis por 24 horas.

Tela hospedada: copie o link Telegram das configurações do offerwall. Funciona em Mini Apps, bots e postagens de canal. A atribuição da fonte é preservada e não cria um relacionamento de referência.

1<script src="https://pixora-ads.com/sdk/pixorads-offerwall.v1.3.3.js"></script>2<pixorads-task publisher-id="YOUR_PUBLISHER_UUID" theme="light">3</pixorads-task>

O componente é executado dentro de um Telegram Mini App usando initData assinado para o bot verificado na propriedade. Nunca exponha uma chave API no navegador. Tema: claro/escuro; altura: variável CSS --pixorads-offerwall-height.

1const client = new PixorAdsOfferwall.Client({ publisherId: "YOUR_PUBLISHER_UUID", telegramInitData: Telegram.WebApp.initData });2// Show terms and obtain consent before connect().3const { items, history, options } = await client.connect({ accepted: true });4// items already honor the publisher's task_types on the server.5// Show an empty state when items is empty; always render history separately.6// Call only when the user chooses a task from items.7async function startSelectedTask(campaignId, retryKey) {8  const task = await client.start(campaignId, retryKey);9  const destination = await client.open(task.id);10  return { task, url: destination.url };11}12// Open the returned protected URL; offer a separate Check button.13async function checkTask(attemptId) {14  return client.check(attemptId);15}16// Do not grant a reward based on a JavaScript event.

API base: https://pixora-ads.com/api/v1/offerwall. Anexe os caminhos /viewer/... e /publisher-api/... mostrados aqui. Cliente ({baseUrl}) aceita apenas uma origem HTTPS, como https://pixora-ads.com, sem caminho, consulta ou hash.

Na chamada de remoção da tela client.disconnect(): as solicitações pendentes falham com a desconexão e o token do visualizador é limpo. Obtenha consentimento e reconecte-se antes de continuar a usar. Após uma resposta perdida, recarregue o histórico; tente novamente iniciar ou enviar o relatório com a chave original porque o servidor pode ter salvo a solicitação. O SDK não tenta novamente automaticamente.

3. Bot API

Exemplos prontos incluem /bonus e /bonusbalance, botões iniciar/verificar, reconciliação após reinicialização, testes de configuração e desduplicação de recompensas. Eles pesquisam o API e não precisam de um webhook público.

• Python 3.11+ · aiograma 3 · httpx
• Node.js 24+ · Telégrafo 4

Cada arquivo começa com comandos de configuração e variáveis de ambiente. Os exemplos dão crédito a um saldo SQLite independente. Para a moeda do seu jogo, coloque o crédito e UNIQUE(conversion_id) em uma transação em seu próprio banco de dados; reconhecer somente após o commit. Não inicie um segundo processo de pesquisa para um bot existente: integre os manipuladores ao seu aplicativo.

Seu servidor bot usa a propriedade API key em X-PixorAds-Key. Solicite uma sessão para um ID Telegram. Se verify=false, mostre verify_url para que o usuário possa verificar sua conta Telegram e aceitar os termos. Um ID arbitrário não pode gerar recompensas. A prova de identidade dura um dia; as solicitações do servidor não o estendem.

1import os, httpx2BASE = "https://pixora-ads.com/api/v1/offerwall"3KEY = os.environ["PIXORADS_KEY"]45async def get_tasks(telegram_user_id):6    async with httpx.AsyncClient(timeout=20) as api:7        r = await api.post(BASE + "/publisher-api/session",8            headers={"X-PixorAds-Key": KEY},9            json={"telegram_id": telegram_user_id})10        r.raise_for_status()11        session = r.json()12        if not session["verified"]:13            return session  # Show verification_url as a button.14        token = session["viewer_token"]15        r = await api.get(BASE + "/viewer/catalog",16            headers={"Authorization": "Bearer " + token})17        r.raise_for_status()18        return {"verified": True, "token": token, **r.json()}1920# Call only after the user selects a task.21async def start_task(token, campaign_id, retry_key):22    async with httpx.AsyncClient(timeout=20) as api:23        r = await api.post(BASE + "/viewer/start",24            headers={"Authorization": "Bearer " + token,25                     "Idempotency-Key": retry_key},26            json={"campaign_id": campaign_id})27        r.raise_for_status()28        return r.json()2930# Send title, reward and conditions. POST /viewer/attempts/{id}/open31# with the viewer token and use its url; for reports use hosted_url.32# A separate Check callback POSTs /viewer/attempts/{task_id}/check.33# Keep tokens on your server and bind callbacks to the same user.34# Store retry_key before the request and reuse it on retries.35# If items is empty, continue the ordinary bot flow.

Um usuário tem um slot separado para tarefas rápidas e pode realizar até cinco tarefas de relatório em mapas, mercados e tarefas estendidas. A revisão e a espera pela entrega não contam para este limite. As tarefas existentes retornadas para revisão ou de entrega permanecem disponíveis. Novas atribuições ficarão indisponíveis enquanto o limite for atingido. A navegação não reserva orçamento e reiniciar a mesma campanha através de outra propriedade não gera uma segunda recompensa.

Lidar com HTTP 409 task_assignment_limit ao iniciar uma tarefa: o limite de tarefa de relatório foi atingido. task_quick_assignment_limit significa que o slot de tarefa rápida está ocupado. Mostre uma mensagem clara e mantenha o cartão selecionado; não mude para uma execução diferente automaticamente. Esses erros não criam nenhuma nova atribuição ou reserva. Quando a capacidade estiver disponível, tente novamente. Após um erro de rede, reutilize a mesma chave de comando.

4. Entregue recompensas no servidor

Configure um webhook HTTPS público. O segredo de assinatura está nas configurações do offerwall. X-PixorAds-Signature = HMAC-SHA256(segredo, carimbo de data / hora + '.' + bytes do corpo bruto); carimbo de data / hora é X-PixorAds-Timestamp. Use verificação de tempo constante e uma distorção de relógio limitada (por exemplo, 5 minutos). Não serialize novamente o JSON antes da verificação.

• completed — ação observada, retenção de membro pendente. Um bônus antecipado é permitido apenas para o modo avançado explicitamente ativado;
• qualified — verificação final aprovada: conceda a recompensa interna uma vez;
• revoked — a verificação de retenção falhou; sem pagamento;
• paid — rendimentos de propriedade liberados de retenção.

Antes de creditar, solicite GET /publisher-api/rewards/{conversion_id}. Verifique telegram_id, reward_mode=partner, test=false e reward_eligible=true. Dê crédito a reward_units dessa resposta exatamente uma vez. Após a confirmação da transação, POST /publisher-api/rewards/{conversion_id}/ack com {reference: 'your credit identifier'}. Tente novamente com a mesma referência após erros de rede. Este reconhecimento aparece para o usuário e nas análises; não aciona Pixora Ads transferências de dinheiro.

5. Bônus flexíveis

Escolha unidades fixas ou unidades por $ 1 de renda de propriedade. As unidades são arredondadas e limitadas pelo mínimo e máximo. Os multiplicadores de promoção têm uma data de término. Os termos congelam no início da tarefa; os preços dos anunciantes e a divisão monetária permanecem inalterados. As estimativas do catálogo podem mudar antes do início se as configurações ou as taxas de câmbio mudarem.

Por padrão, conceda após a verificação final. Na modalidade antecipada, a propriedade concede seu próprio bônus após a verificação inicial por sua conta e risco: a não manutenção da adesão cancela os rendimentos da propriedade. Pixora Ads não recupera bônus internos gastos. As recompensas em dinheiro e a liberação de receitas não são aceleradas.

Use Conversion_id como chave de recompensa e salve-o atomicamente com a recompensa sob uma restrição UNIQUE. Desduplicar event_id. Os eventos podem ser repetidos ou chegar fora de ordem. Devolva 2xx somente após armazenamento durável. Até 12 tentativas de entrega; erros e novas tentativas manuais estão disponíveis no painel de propriedades.

Se estiver usando o recibo de um resultado final, envie-o para o seu servidor: POST /publisher-api/reward/verify com a chave da propriedade. Combine telegram_id e Conversion_id com seu usuário. Um recibo não substitui a desduplicação de pagamento. Sem webhooks, histórico de enquetes e resultados finais.

1{2  "campaign_id": "CAMPAIGN_UUID",3  "attempt_token": "px_ATTEMPT_TOKEN",4  "event_id": "your-stable-event-id",5  "telegram_id": 123456789,6  "event_name": "tutorial_complete",7  "occurred_at": "2026-10-06T10:05:00Z",8  "first_seen_at": "2026-10-06T10:01:00Z",9  "status": "completed",10  "reason": null11}

Relatórios e limites

Passe o posicionamento para o Cliente, como um atributo de componente ou em uma solicitação de sessão API. Use de 1 a 40 letras ASCII, dígitos _ ou -. O widget reporta um cartão quando pelo menos 50% está visível. Em uma interface de usuário personalizada, chame client.visible([campaignId]) após a exibição real, não o carregamento do catálogo. A visibilidade da mensagem do bot é desconhecida, portanto, não relate a visibilidade do cartão lá.

O suporte está vinculado a uma execução: POST /viewer/attempts/{id}/ticket com {message: 'description'} ou client.support(id, message). A resposta aparece em histórico[].ticket. Os editores veem suas próprias solicitações; os operadores respondem em Rede de anúncios → Offerwall suporte.

O painel de relatórios inicia, verificações de retenção, resultados confirmados, cancelamentos, gastos de anunciantes e receitas de propriedade. Os períodos referem-se à data de início da tarefa. Uma solicitação de catálogo não é uma impressão de anúncio, alcance único ou ação faturável. O faturamento inclui apenas os resultados finais verificados.

Use init({publisherId, trackAudience:true}); este é o padrão do init(). Defina falso para cancelar. trackVisit() usa Telegram initData assinado com no máximo uma hora. A instalação apenas em um espaço de anúncio mede seus visitantes, não todo o público do seu aplicativo.

Chame trackVisit() em retornos significativos sem pesquisa. O servidor desduplica pessoas. gravado:falso significa que nenhuma observação foi salva, nem uma falha no anúncio. trackAudience:false desativa o envio automático, mas não bloqueia uma chamada trackVisit() explícita.

Os bots relatam atividade genuína via POST /api/v1/ad-network/publisher-api/activity com {telegram_id} e uma chave X-PixorAds somente para servidor. Estas são observações relatadas por parceiros, não evidências pagas. Os canais atualizam as contagens de assinantes após a verificação do administrador; os assinantes não têm alcance de publicidade.

Atividade durante 24 horas/7/30 dias, visualizadores de anúncios únicos, impressões visíveis e visualizações concluídas são separados. As previsões precisam de sete dias UTC completos para cada propriedade selecionada; o histórico de segmentação sem suporte não produz estimativa. Os públicos medidos são desduplicados; os assinantes do canal não são somados. Grupos com menos de 20 anos ficam ocultos dos anunciantes.

Divulgue a medição aos usuários. Habilite personalizado:true somente com permissão para usar um perfil Pixora Ads existente. Nunca substitua initDataUnsafe por initData assinado. As observações de atividades usam identificadores HMAC retidos por até 90 dias.

O real SDK abaixo é executado com test: true. Nenhum anúncio é solicitado e nenhum dinheiro ou alteração de estatísticas. Clique no botão do cartão. Use o mesmo modo em sua página; não requer nenhum ponto final.

1window.PixorAdsPublisher.mount({2  element: document.getElementById("pixorads"),3  language: "pt",4  test: true5});

Novas integrações: init() → método escolhido → destroy() ao remover a tela. Legacy create() requer elemento; mount() usa seleção automática e retorna uma promessa de estado. PixorAdsPublisher.mount(options) não expõe nenhum controlador; use init() ou create() para gerenciamento do ciclo de vida.

Tempo de execução e CSP

A visualização incorporada ao vivo requer HTTPS e uma inicialização Telegram com initData assinado com no máximo uma hora. Use test:true em um navegador comum; initDataUnsafe não é prova de identidade. Atualize os dados de lançamento expirados reabrindo o Mini App, não alterando auth_date.

Permitir https://pixora-ads.com em script-src, frame-src e connect-src; permitir ativos de cartão em img-src e media-src. Mantenha as permissões existentes do seu aplicativo. Se o CSP restringir estilos, verifique a compatibilidade: SDK aplica estilos embutidos ao seu cartão e sobreposição. Nunca envie a chave API para o navegador.

TypeScript: salve o .d.ts em uma pasta incluída pelo tsconfig e use window.PixorAdsPublisher. Estas declarações descrevem um script global, não um módulo npm. Não existe um pacote npm oficial.

1curl https://pixora-ads.com/api/v1/ad-network/publisher-api/offer \2  -H "X-PixorAds-Key: $PIXORADS_PUBLISHER_KEY" \3  -H "Idempotency-Key: unique-logical-request-id" \4  -H "Content-Type: application/json" \5  -d '{"language":"en","format":"native"}'

Exemplo de resposta

Abaixo está um exemplo abreviado de recompensa. Retorne o JSON upstream completo inalterado, incluindo URLs, formato e campos de contabilidade. Faturamento de uso nativo/intersticial = confirm_impression e inclui impression_url. recompensa e publisher_amount são unidades inteiras menores: divida XTR e RUB por 1000, USD por 1.000.000. Recompensa do visualizador: viewer_reward/viewer_currency. Ganhos estimados de USD editores: publisher_income.

1{2  "source": "pixorads",3  "placement_id": "<placement UUID>",4  "title": "<advertisement title>",5  "text": "<plain text>",6  "disclosure": "Реклама · Ad · Pixora Ads",7  "url": "https://t.me/pixoradsbot?startapp=net_<32 hex characters>",8  "expires_at": "<ISO 8601 timestamp>",9  "format": "rewarded",10  "billing": "completed_rewarded_session",11  "currency": "XTR",12  "reward": 70,13  "publisher_amount": 114}15// No suitable demand: { "source": "none", "monetag_enabled": false }16// Rewarded response excerpt, not a complete offer to return from your backend.17// Example: 70 XTR minor units = 0.07 Stars; 1 = 0.001 Stars.18// Ordinary: billing:"confirmed_impression", reward:0, impression_url present.19// Forward the FULL upstream JSON unchanged; never build it from this excerpt.

As colocações normais duram cinco minutos; as colocações premiadas duram 24 horas. Siga expira_at. Chave de Idempotência: até 80 caracteres, um por solicitação lógica. Novas tentativas recompensadas reproduzem a resposta. A repetição de uma oferta comum emitida retorna posicionamento_already_issued: solicite um novo posicionamento com uma nova chave. Evite loops de repetição.

As estatísticas de propriedades mostram sessões emitidas, conclusões verificadas, receitas retidas e receitas liberadas. As impressões comuns confirmadas são separadas das conclusões premiadas; uma solicitação de oferta, renderização de cartão ou clique por si só não comprova ganhos. Os ganhos são acumulados em USD. Mini Apps: 80% durante a promoção atual, depois 70%; campanhas de novos canais: 90%, depois 88%; bot CPC tem uma taxa independente. As taxas atuais aparecem nos ganhos imobiliários. Anúncios comuns usam receita de impressões pagas; Recompensado usa a receita após a recompensa do espectador. Os preços e as ações dos canais são fixados na criação da campanha e o câmbio na pós-reserva. Mini App os prazos são fixados na emissão e USD na confirmação. Histórico RUB e Estrelas permanecem separados. USD as retiradas usam apenas criptografia. As taxas dependem dos lances do leilão e da demanda disponível. As restrições podem manter a renda sob revisão.

Entre em contato com o suporte com o ID da propriedade, hora do erro, status HTTP e código. Não envie sua chave API ou token de bot.

Selecione formatos ao registrar sua propriedade para moderação. Imagens e vídeos são tipos criativos; nativo, intersticial e recompensado são cenários de entrega. Não existe um método showVideo() separado: o servidor seleciona um criativo correspondente.

Mini App a publicidade fica dentro da interface do parceiro. A navegação do anunciante é opcional; descartar o anúncio retorna à sua tela. Os bots usam anúncios de conversação pagos por clique; canais usam postagens com CPM ou CPC. O CTA leva ao anunciante. Este JavaScript SDK é para Mini Apps, não para mensagens.

A receita do editor e os bônus dos espectadores são separados. Use nativo ou intersticial para monetizar sem recompensas. As impressões comuns exigem pelo menos 50% de visibilidade criativa por um segundo contínuo em uma janela ativa e reprodução real do vídeo. O servidor verifica a elegibilidade, limites e orçamento antes de confirmar a entrega.

Para novas integrações use SDK 1.8.4: init() e um método show explícito. O legado create()/mount() permanece compatível.

Envie marcos de referência para Keitaro, Binom v2 ou seu servidor. Esta é uma análise de saída: ela não altera os pagamentos nem substitui os webhooks de recompensa Offerwall ou a confirmação do servidor Pixel.

1. Conecte seu rastreador

Parceiros → Links → Postbacks: escolha um rastreador, insira seu endpoint HTTPS público, adicione metas e links salvos. Visualize a solicitação gerada, teste a entrega e habilite a integração. Uma integração pode servir vários links; cada link possui uma integração.

2. Preserve o ID de clique do seu rastreador

1# Keitaro2https://pixora-ads.com/api/v1/referrals/track/YOUR_LINK_CODE?tracker_click_id={subid}34# Binom5https://pixora-ads.com/api/v1/referrals/track/YOUR_LINK_CODE?tracker_click_id={clickid}

Use o código do seu link salvo; seu rastreador substitui sua macro de clique. tracker_click_id é o identificador externo (até 128 caracteres); click_id é o ID interno separado de Pixora. A ponte salva o ID externo e abre o site, bot ou Mini App selecionado. Um link direto Telegram com valores de sub_id fixos não captura o ID de clique dinâmico do rastreador.

3. Escolha metas e valores

Até 24 gols por integração. amount é o valor do evento; o pagamento é a renda do parceiro: o depósito de 1.000 RUB de uma indicação não representa 1.000 RUB da receita do parceiro. Apenas a comissão gera pagamento monetário por padrão. As moedas permanecem separadas; As estrelas não são convertidas em rublos ou dólares. Nas configurações API, amount_minor é uma string inteira: RUB e XTR usam 1.000 unidades, USD 1.000.000. O valor de saída e o pagamento são sequências decimais em suas moedas.

Keitaro recebe um tid estável por gol e evento para que novas tentativas não adicionem outra conversão. No Binom, reserve event1…event24 e uma moeda de pagamento, RUB ou USD. O adaptador envia valores absolutos de eventos e receita cumulativa com disable_upsell=1 e disable_postback=1. Não os adicione novamente nas regras do seu rastreador.

Endpoint personalizado: GET ou POST

1https://tracker.example/pixora?click={tracker_click_id}&goal={goal_id}&event={event}&amount={amount}&currency={currency}&payout={payout}&payout_currency={payout_currency}

Macros são permitidas apenas em valores de consulta: tracker_click_id, click_id, event_id, goal_id, event, link_id, sub_id_1…sub_id_5, quantidade, moeda, pagamento, payout_currency e ocorreu_at. Coloque os nomes das macros entre colchetes. status, meta e quantidade_minor não são macros. event_id e tracker_click_id são adicionados a solicitações GET personalizadas mesmo quando omitidos em seu modelo.

POST envia JSON fixo com esses campos mais schema_version=1, test_mode, event_type e corrects_event_id; não é um modelo de corpo personalizado. Armazene event_id com uma restrição UNIQUE na mesma transação do processamento e retorne 2xx para duplicatas. Um event_type=correction faz referência ao seu evento original por meio de corrects_event_id. Nunca credite usuários reais em eventos test_mode=true.

Entrega, novas tentativas e diário

A visualização não envia nenhuma solicitação. Um teste de entrega usa um ID px_test_… sintético; HTTP 2xx prova apenas uma resposta de endpoint, não uma conversão de rastreador. Para uma verificação de ponta a ponta, siga o link do seu rastreador e alcance uma meta. O diário mostra o evento, o status e o motivo do erro enquanto mascara os parâmetros secretos.

As falhas de rede 429 e 5xx são repetidas com backoff, até 8 tentativas automáticas por ciclo. Outros 4xx e redirecionamentos interrompem a entrega. A nova tentativa manual mantém o event_id, URL e carga útil originais. Um evento com falha bloqueia eventos posteriores para esse clique externo: restaure o endpoint e tente novamente. As alterações nas configurações se aplicam a visitas futuras sem reenvio do histórico. A atribuição de referência original é preservada.

Gerenciamento API: /api/v1/referrals/postbacks, somente proprietário autenticado. Listas GET e criações POST; /{id} suporta GET e PUT; /{id}/events é o diário; /preview e /{id}/preview renderizam uma solicitação; /{id}/test e /events/{event_id}/retry entregam explicitamente. Criar, salvar, testar e tentar novamente exigem chave de idempotência (1 a 96 caracteres); as atualizações precisam da versão atual. O editor X-PixorAds-Key não é usado aqui.