Pixora Ads SDK y API para desarrolladores

Seleccione formatos al registrar su propiedad para moderación. Las imágenes y los vídeos son tipos creativos; nativo, intersticial y recompensado son escenarios de entrega. No existe un método showVideo() independiente: el servidor selecciona una creatividad coincidente.

Mini App la publicidad permanece dentro de la interfaz del socio. La navegación del anunciante es opcional; al descartar el anuncio vuelve a su pantalla. Los bots utilizan anuncios de conversación pagados por clic; Los canales usan publicaciones con CPM o CPC. La CTA conduce al anunciante. Este JavaScript SDK es para Mini Apps, no para mensajes.

Los ingresos del editor y las bonificaciones de los espectadores son independientes. Utilice anuncios nativos o intersticiales para monetizar sin recompensas. Las impresiones normales requieren al menos un 50 % de visibilidad creativa durante un segundo continuo en una ventana activa y reproducción real de vídeo. El servidor verifica la elegibilidad, los límites y el presupuesto antes de confirmar la entrega.

Para nuevas integraciones, utilice SDK 1.8.4: init() y un método show explícito. Legacy create()/mount() sigue siendo compatible.

1. Abra Monetización → Propiedades → Conecte una propiedad y elija Mini App, bot o canal público.
2. Proporcione un nombre, Telegram URL y una descripción del tema y la audiencia. Para Mini Apps utilice el enlace del bot o un enlace directo t.me/bot/appname. Seleccione nativo, intersticial y/o recompensado antes de la moderación. Describa la ubicación del anuncio en la descripción; no hay ningún campo separado.
3. Verificar control: token de bot para bots/Mini Apps; Permisos de administrador para canales. El token verifica el control del bot; un moderador revisa la ubicación.
4. Para Mini Apps y bots, cree una clave API después de la aprobación y manténgala en el lado del servidor. La publicación automática del canal no necesita un servidor separado o una clave API: guarde la configuración de publicación y verifique los permisos del bot.
5. Ejecute la prueba a continuación, conecte su backend y SDK o prepare un anuncio en el panel. Los anuncios en vivo requieren una propiedad activa y una demanda coincidente; La conexión no garantiza el llenado de anuncios ni ingresos.

La demostración de @pixorAds_networkbot muestra el recorrido completo del usuario: abriendo un Mini App, solicitando un anuncio a través de un servidor y mostrando el formato elegido dentro del Mini App. Puedes probarlo antes de conectar tu propia propiedad.

1. Abra el bot y ejecute su Mini App. El backend de demostración verifica la sesión Telegram a través de /api/v1/ad-network/demo/session.
2. El SDK llama a /api/v1/ad-network/demo/offer en el mismo origen. La clave secreta del editor permanece en el servidor.
3. Si no hay ninguna oferta paga equivalente, la aplicación de demostración muestra un video introductorio. Este es el estado vacío del editor, no una vista de anuncio: no genera ningún cargo, recompensa ni ingresos para el 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: "es"16});17await placement.showNative();

Cargue el script una vez en HTML. Establezca el punto final en su propio backend en el mismo origen. Nunca expongas la tecla API al navegador. Antes de init(), envíe Telegram.WebApp.initData a su backend: verifique su firma y antigüedad, cree una sesión y, para la autenticación de cookies, devuelva un token CSRF para la opción csrfToken. Copie el ID del editor público de la tarjeta de propiedad. Los ejemplos siguientes son anuncios nativos sin recompensas; consulte Mostrar métodos para otros escenarios. Pase el token CSRF de la sesión como accesorio de React y destruya() al desmontar.

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>

Elija un ejemplo a continuación. Cargue el SDK y haga que su servidor verifique primero la sesión Telegram. Reemplace PublisherId con su ID de propiedad pública. csrfTokenFromYourSession es el token CSRF de su sesión, no una clave API. /api/pixorads/offer es una ruta que implementas en tu 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 del 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}

Sólo se puede abrir un visor de anuncios a la vez. No ejecute showNative() y un método de pantalla completa simultáneamente en un controlador. Continúe su aplicación en no_fill; Nunca reemplace una recompensa prometida con un anuncio común y corriente. Destruye el controlador cuando se retira la pantalla, no inmediatamente después de renderizar una tarjeta.

Los nativos y los intersticiales no necesitan integración de recompensa. En modo recompensado Pixora Ads verifica la vista; su backend otorga monedas, vidas u otros bonos adicionales dentro de su aplicación.

1. Lea el recibo opaco de showRewarded() después del despido. Es una prueba para verificar, no un monto de recompensa.
2. Envíelo a su backend autenticado. Verifíquelo usando la clave de esta propiedad y haga coincidir telegram_id con su propio usuario de sesión.
3. En una transacción, guarde el recibo_id único y otorgue el bono configurado por el servidor. Las solicitudes repetidas deben devolver el resultado existente sin conceder dos veces.

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.

Respuesta: recompensado, recibo_id, sesión_id, editor_id, telegrama_id, operación_id, recompensa, moneda, completado_en. Los recibos duran siete días y están vinculados a la propiedad. La verificación no transfiere dinero. Si su backend no está disponible, vuelva a intentar obtener el mismo recibo en lugar de requerir otra visualización del anuncio.

Cuándo usar onReward

onReward({receipt, session_id}) se activa al finalizar mientras el visor puede permanecer abierto. Es una alternativa a la tramitación del recibo tras el despido. El SDK no espera ni vuelve a intentar su devolución de llamada asíncrona: implemente errores y vuelva a intentarlo usted mismo. Si utiliza ambas rutas, la deduplicación del servidor mediante recibo_id es esencial. Las notificaciones de eventos y los clics en CTA nunca autorizan una bonificación.

API las cantidades son unidades menores enteras: XTR / 1000 = Estrellas; RUB / 1000 = rublos; USD / 1.000.000 = dólares. recompensa: 70 con moneda: XTR significa 0,07 estrellas. En una oferta, visor_recompensa/visor_moneda describen la recompensa del espectador; recompensa y monto_editor utilizan la moneda de la campaña. Publisher_Ingresos estima USD ganancias, fijadas en la confirmación. Ninguno de los dos define la cantidad de monedas en su aplicación.

Su backend autentica al usuario, limita las solicitudes y solicita un anuncio de Pixora Ads. Reenvía la respuesta JSON al widget. Reutilice una clave de idempotencia para reintentos de la misma solicitud lógica; Utilice una nueva clave para una nueva 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 o revocar una clave la desactiva y sus enlaces de ubicación. Actualice su variable de entorno y cree nuevas ubicaciones. Las sesiones iniciadas conservan sus términos, pero las nuevas acciones de los espectadores verifican el estado actual y la versión clave.

El formato principal del bot es un anuncio tras una respuesta útil, pagado por visita confirmada. Los tokens de BotFather permanecen en el servidor propietario; los espectadores no necesitan registrarse por separado.

Configure la entrega, apruebe creatividades y vea tarifas e ingresos en la tarjeta de propiedad del bot en Anuncios de conversación. La visualización recompensada sigue siendo un formato opcional con su propia integración.

Agrega un canal público con tu cuenta y el bot Pixora Ads como administradores. Después de la moderación, verifique los permisos de publicación y eliminación. Elija vistas (CPM, predeterminado) o clics confirmados (CPC) en la configuración del canal. Establezca ganancias mínimas y el límite de resultados por publicación. La publicación y aprobación automáticas están disponibles para ambos.

CPM paga Telegram vistas de contador en las primeras 24 horas, incluidos los forwards; este no es un alcance o una finalización únicos. CPC paga navegación confirmada en una página corta sin registro. Las vistas, vistas previas y repeticiones del mismo anunciante en canales dentro de las 24 horas son gratuitas. Una huella digital de IP y de agente de usuario no es prueba de una persona única. Los lectores no reciben ninguna recompensa.

La liquidación sigue a la colocación de 24 horas y luego a la suspensión de la campaña. El historial de publicaciones muestra ganancias, vistas pagas o clics y fechas de lanzamiento. Los precios y las acciones del canal son independientes de Mini Apps; Las tasas actuales aparecen en las ganancias de la propiedad.

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 · Conexión, entorno de pruebas no financiero, bonificaciones y diagnósticos en un solo panel.

Un catálogo de tareas: una pantalla alojada, Mini App componente y API para su propia interfaz o Telegram bot. Se admiten suscripciones a canales públicos y uniones a grupos. Pixora Ads debe ser administrador del chat de destino. Los primeros lanzamientos de bots y las acciones Mini App confirmadas por el anunciante también se admiten después de una prueba de integración. Se admiten reacciones de grupos públicos, encuestas Pixora Ads no anónimas, nuevos aumentos Premium, visitas a sitios web, navegación y tareas de informes, incluida la investigación de productos. La disponibilidad del sitio web depende de la configuración del servicio. No se admiten formatos de compra dedicados ni tareas de varios pasos.

1. Prepare su propiedad

Agregue y verifique una propiedad en Mis propiedades y complete la moderación. En Tareas y recompensas, elija el modo de recompensa, configure las devoluciones de llamadas y habilite las tareas. Solo son elegibles las campañas cuyos anunciantes habilitaron explícitamente la distribución de socios.

• Pixora Ads recompensa: un usuario registrado gana dinero en efectivo; la propiedad gana una parte de la tarifa de la plataforma. Participación inicial: 50% de la cuota.
• Recompensa de propiedad: otorgas monedas o acceso; su propiedad gana una parte del precio resultante. Participación inicial: 80%. Su servidor ofrece recompensas internas.

Los recursos compartidos son configurables y congelados cuando comienza una tarea. Los ingresos de la propiedad se registran en USD a un tipo de cambio congelado y se retienen después de la verificación final (24 horas por defecto). La retención de membresía se muestra por separado. Una acción confirmada no significa que los ingresos se puedan retirar inmediatamente.

Las recompensas por referencias de tareas se financian con la parte restante de la plataforma después de la división del editor. No reducen la recompensa de usuario acordada ni los ingresos de la propiedad.

2. Elige una integración

Antes de habilitar tareas, abra Monetización → Offerwall → Conexión. Guarde la configuración, cree una tarea de muestra y complétela. Su evento tiene test=true, user_id=null y cero ingresos monetarios. Nunca le des crédito a un usuario real por ello. Repita la prueba después de cambiar la configuración.

Con los webhooks, la prueba se envía a la URL guardada con la firma HMAC habitual. De lo contrario, busque GET /publisher-api/tests. Su servidor lo reconoce a través de POST /publisher-api/tests/{conversion_id}/ack con X-PixorAds-Key. HTTP 2xx por sí solo no confirma una recompensa. Los eventos de prueba permanecen disponibles durante 24 horas.

Pantalla alojada: copie el enlace Telegram desde la configuración del muro de ofertas. Funciona en Mini Apps, bots y publicaciones de canales. La atribución de la fuente se conserva y no crea una relación de referencia.

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>

El componente se ejecuta dentro de un Telegram Mini App utilizando initData firmado para el bot verificado en la propiedad. Nunca expongas una clave API en el navegador. Tema: claro/oscuro; altura: variable 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. Agregue las rutas /viewer/... y /publisher-api/... que se muestran aquí. El cliente ({baseUrl}) acepta solo un origen HTTPS, como https://pixora-ads.com, sin ruta, consulta o hash.

Llamada de eliminación en pantalla client.disconnect(): las solicitudes pendientes fallan y se desconectan y el token del espectador se borra. Obtenga el consentimiento y vuelva a conectarse antes de seguir usándolo. Después de una respuesta perdida, recarga el historial; Vuelva a intentar iniciar o enviar el informe con la clave original porque es posible que el servidor haya guardado la solicitud. El SDK no vuelve a intentarlo automáticamente.

3. Bot API

Los ejemplos listos incluyen /bonus y /bonusbalance, botones de inicio/verificación, conciliación después del reinicio, pruebas de configuración y deduplicación de recompensas. Sondean el API y no necesitan un webhook público.

• Python 3.11+ · diagrama 3 · httpx
• Node.js 24+ · Telegraf 4

Cada archivo comienza con comandos de configuración y variables de entorno. Los ejemplos acreditan un saldo SQLite independiente. Para la moneda de tu juego, coloca el crédito y UNIQUE(conversion_id) en una transacción en tu propia base de datos; reconocer sólo después de comprometerse. No inicie un segundo proceso de sondeo para un bot existente: integre los controladores en su aplicación.

Su servidor bot usa la propiedad API clave en X-PixorAds-Key. Solicita una sesión para un Telegram ID. Si verificado = falso, muestra la URL de verificación para que el usuario pueda verificar su cuenta Telegram y aceptar los términos. Una identificación arbitraria no puede generar recompensas. La prueba de identidad dura un día; Las solicitudes del servidor no lo amplían.

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.

Un usuario tiene un espacio separado para tareas rápidas y puede realizar hasta cinco tareas de informes en mapas, mercados y tareas extendidas. La revisión y la espera de la entrega no cuentan para este límite. Las tareas existentes que regresan para revisión o desde la entrega permanecen disponibles. Las nuevas asignaciones no están disponibles mientras se alcanza el límite. La navegación no reserva presupuesto y reiniciar la misma campaña a través de otra propiedad no crea una segunda recompensa.

Manejar HTTP 409 task_assignment_limit al iniciar una tarea: se alcanza el límite de tarea de informe. task_quick_assignment_limit significa que el espacio de tarea rápida está ocupado. Mostrar un mensaje claro y conservar la tarjeta seleccionada; no cambie automáticamente a una ejecución diferente. Estos errores no crean ninguna nueva asignación o reserva. Una vez que haya capacidad disponible, vuelva a intentarlo. Después de un error de red, reutilice la misma clave de comando.

4. Entregar recompensas en el servidor.

Configure un webhook HTTPS público. El secreto de firma está en la configuración del muro de ofertas. X-PixorAds-Signature = HMAC-SHA256(secreto, marca de tiempo + '.' + bytes de cuerpo sin formato); la marca de tiempo es X-PixorAds-Timestamp. Utilice la verificación de tiempo constante y una desviación horaria limitada (por ejemplo, 5 minutos). No vuelva a serializar JSON antes de la verificación.

• completed — acción observada, retención de membresía pendiente. Se permite una bonificación anticipada solo para el modo avanzado explícitamente habilitado;
• qualified — verificación final aprobada: otorga la recompensa interna una vez;
• revoked — la verificación de retención falló; sin pago;
• paid — ingresos de la propiedad liberados de la retención.

Antes de acreditar, solicite GET /publisher-api/rewards/{conversion_id}. Verifique telegram_id,reward_mode=partner, test=false yreward_eligible=true. Acredite las unidades de recompensa de esa respuesta exactamente una vez. Después de que se confirme su transacción, PUBLICAR /publisher-api/rewards/{conversion_id}/ack con {reference: 'your credit identifier'}. Vuelva a intentarlo con la misma referencia después de los errores de red. Este reconocimiento le aparece al usuario y en análisis; no activa Pixora Ads transferencias de dinero.

5. Bonos flexibles

Elija unidades fijas o unidades por $1 de ingreso de propiedad. Las unidades se redondean hacia abajo y están limitadas por su mínimo y máximo. Los multiplicadores de promoción tienen fecha de finalización. Los términos se congelan al inicio de la tarea; Los precios de los anunciantes y la división monetaria se mantienen sin cambios. Las estimaciones del catálogo pueden cambiar antes del inicio si cambian la configuración o los tipos de cambio.

De forma predeterminada, se otorga después de la verificación final. En la modalidad anticipada, la propiedad otorga su propio bono después del control inicial bajo su propia responsabilidad: la falta de retención de la membresía cancela los ingresos de la propiedad. Pixora Ads no recupera las bonificaciones internas gastadas. Las recompensas en efectivo y la liberación de ingresos no se aceleran.

Utilice conversion_id como clave de recompensa y guárdela de forma atómica con la recompensa bajo una restricción ÚNICA. Deduplicar event_id. Los eventos pueden repetirse o llegar desordenados. Devuelva 2xx solo después de un almacenamiento duradero. Hasta 12 intentos de entrega; Los errores y los reintentos manuales están disponibles en el panel de propiedades.

Si utiliza el recibo de un resultado final, envíelo a su servidor: POST /publisher-api/reward/verify con la clave de propiedad. Haga coincidir telegram_id y conversion_id con su usuario. Un recibo no reemplaza la deduplicación de pagos. Sin webhooks, historial de encuestas y resultados finales.

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}

Informes y límites

Pase la ubicación al Cliente, como atributo de componente o en una solicitud de sesión API. Utilice entre 1 y 40 letras ASCII, dígitos, _ o -. El widget informa una tarjeta cuando al menos el 50% es visible. En una interfaz de usuario personalizada, llame a client.visible([campaignId]) después de la visualización real, no de la carga del catálogo. Se desconoce la visibilidad de los mensajes del bot, así que no informe sobre la visibilidad de la tarjeta allí.

El soporte está vinculado a una ejecución: POST /viewer/attempts/{id}/ticket con {message: 'description'}, o client.support(id, mensaje). La respuesta aparece en historial[].ticket. Los editores ven sus propias solicitudes; los operadores responden en Red publicitaria → Offerwall soporte.

El panel informa inicios, verificaciones de retención, resultados confirmados, cancelaciones, gastos de anunciantes e ingresos de propiedad. Los períodos se refieren a la fecha de inicio de la tarea. Una solicitud de catálogo no es una impresión de anuncio, un alcance único ni una acción facturable. La facturación incluye sólo los resultados finales verificados.

Utilice init({publisherId, trackAudience:true}); este es el valor predeterminado de init(). Establezca false para optar por no participar. trackVisit() utiliza Telegram initData firmado como máximo con una hora de antigüedad. La instalación solo en un espacio publicitario mide a sus visitantes, no a toda la audiencia de su aplicación.

Llame a trackVisit() en retornos significativos sin sondeo. El servidor deduplica a las personas. registrado: falso significa que no se guardó ninguna observación, ni un error en el anuncio. trackAudience:false deshabilita el envío automático pero no bloquea una llamada explícita a trackVisit().

Los bots informan actividad genuina a través de POST /api/v1/ad-network/publisher-api/activity con {telegram_id} y una clave X-PixorAds-Key exclusiva del servidor. Estas son observaciones informadas por socios, no evidencia de visualización paga. Los canales actualizan el recuento de suscriptores después de la verificación del administrador; Los suscriptores no son alcance publicitario.

La actividad durante 24 horas/7 días/30 días, los espectadores de anuncios únicos, las impresiones visibles y las vistas completadas están separadas. Los pronósticos necesitan siete días UTC completos para cada propiedad seleccionada; El historial de segmentación no admitido no produce ninguna estimación. Las audiencias medidas se deduplican; Los suscriptores del canal no se suman. Los grupos inferiores a 20 están ocultos para los anunciantes.

Divulgar la medición a los usuarios. Habilite personalizado: verdadero solo con permiso para usar un perfil Pixora Ads existente. Nunca sustituya initDataUnsafe por initData firmado. Las observaciones de actividad utilizan identificadores HMAC retenidos por hasta 90 días.

El SDK real a continuación se ejecuta con test: true. No se solicitan anuncios ni cambios de dinero ni estadísticas. Haga clic en el botón de la tarjeta. Utilice el mismo modo en su página; no requiere ningún punto final.

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

Nuevas integraciones: init() → método elegido → destroy() al quitar la pantalla. La creación heredada () requiere un elemento; mount() utiliza la selección automática y devuelve una promesa de estado. PixorAdsPublisher.mount(opciones) no expone ningún controlador; utilice init() o create() para la gestión del ciclo de vida.

Tiempo de ejecución y CSP

La visualización integrada en vivo requiere HTTPS y un inicio Telegram con initData firmado con una antigüedad máxima de una hora. Utilice test:true en un navegador normal; initDataUnsafe no es una prueba de identidad. Actualice los datos de lanzamiento caducados volviendo a abrir Mini App, no cambiando auth_date.

Permitir https://pixora-ads.com en script-src, frame-src y connect-src; permitir activos de tarjeta en img-src y media-src. Conserve los permisos existentes de su aplicación. Si CSP restringe los estilos, verifique la compatibilidad: SDK aplica estilos en línea a su tarjeta y superposición. Nunca envíe la clave API al navegador.

TypeScript: guarde los .d.ts en una carpeta incluida por tsconfig y use window.PixorAdsPublisher. Estas declaraciones describen un script global, no un módulo npm. No existe un paquete 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"}'

Ejemplo de respuesta

A continuación se muestra un ejemplo recompensado abreviado. Devuelve el JSON ascendente completo sin cambios, incluidas las URL, el formato y los campos de contabilidad. Facturación de uso nativo/intersticial = impresión_confirmada e incluye URL de impresión. recompensa y cantidad_editor son unidades enteras menores: divida XTR y RUB entre 1000, USD entre 1.000.000. Recompensa del espectador: visor_recompensa/visor_moneda. Ingresos estimados del editor USD: editor_ingresos.

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.

Las colocaciones ordinarias duran cinco minutos; Las ubicaciones premiadas duran 24 horas. Siga expires_at. Clave de idempotencia: hasta 80 caracteres, uno por solicitud lógica. Los reintentos recompensados ​​reproducen la respuesta. La repetición de una oferta ordinaria emitida devuelve una ubicación_already_emitida: solicita una nueva ubicación con una nueva clave. Evite los bucles de reintento.

Las estadísticas de propiedad muestran sesiones emitidas, terminaciones verificadas, ingresos retenidos e ingresos liberados. Las impresiones ordinarias confirmadas son independientes de las completaciones recompensadas; una solicitud de oferta, una presentación de tarjeta o un clic por sí solo no prueba ganancias. Las ganancias se acumulan en USD. Mini Apps: 80% durante la promoción actual, luego 70%; campañas de nuevos canales: 90%, luego 88%; bot CPC tiene una tarifa independiente. Las tasas actuales aparecen en las ganancias de la propiedad. Los anuncios comunes utilizan ingresos por impresiones pagas; Recompensado utiliza los ingresos después de la recompensa del espectador. Los precios y las acciones del canal se fijan en el momento de la creación de la campaña y los cambios en el momento de la reserva. Mini App los términos se fijan en el momento de la emisión y USD en el momento de la confirmación. El histórico RUB y las Estrellas siguen separados. USD los retiros utilizan únicamente criptomonedas. Las tarifas dependen de las ofertas de la subasta y de la demanda disponible. Las restricciones pueden mantener los ingresos bajo revisión.

Póngase en contacto con el soporte con el ID de propiedad, la hora del error, el estado HTTP y el código. No envíe su clave API ni su token de bot.

Seleccione formatos al registrar su propiedad para moderación. Las imágenes y los vídeos son tipos creativos; nativo, intersticial y recompensado son escenarios de entrega. No existe un método showVideo() independiente: el servidor selecciona una creatividad coincidente.

Mini App la publicidad permanece dentro de la interfaz del socio. La navegación del anunciante es opcional; al descartar el anuncio vuelve a su pantalla. Los bots utilizan anuncios de conversación pagados por clic; Los canales usan publicaciones con CPM o CPC. La CTA conduce al anunciante. Este JavaScript SDK es para Mini Apps, no para mensajes.

Los ingresos del editor y las bonificaciones de los espectadores son independientes. Utilice anuncios nativos o intersticiales para monetizar sin recompensas. Las impresiones normales requieren al menos un 50 % de visibilidad creativa durante un segundo continuo en una ventana activa y reproducción real de vídeo. El servidor verifica la elegibilidad, los límites y el presupuesto antes de confirmar la entrega.

Para nuevas integraciones, utilice SDK 1.8.4: init() y un método show explícito. Legacy create()/mount() sigue siendo compatible.

Envíe hitos de referencia a Keitaro, Binom v2 o su servidor. Se trata de análisis salientes: no cambia los pagos ni reemplaza los webhooks de recompensa Offerwall ni la confirmación del servidor Pixel.

1. Conecta tu rastreador

Socios → Enlaces → Devoluciones de datos: elija un rastreador, ingrese su punto final HTTPS público, agregue objetivos y enlaces guardados. Obtenga una vista previa de la solicitud generada, pruebe la entrega y habilite la integración. Una integración puede servir a varios enlaces; cada enlace tiene una integración.

2. Conserve el ID de clic de su 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}

Utilice el código de su enlace guardado; su rastreador sustituye su macro de clic. tracker_click_id es el identificador externo (hasta 128 caracteres); click_id es el ID interno independiente de Pixora. El puente guarda la ID externa y abre el sitio web seleccionado, bot o Mini App. Un enlace directo Telegram con valores sub_id fijos no captura el ID de clic dinámico del rastreador.

3. Elige objetivos y montos

Hasta 24 goles por integración. cantidad es la cantidad del evento; El pago son ingresos del socio: el depósito de 1000 RUB de una referencia no son 1000 RUB de ingresos del socio. Sólo la comisión genera un pago monetario de forma predeterminada. Las monedas permanecen separadas; Las estrellas no se convierten a rublos ni a dólares. En la configuración API, cantidad_minor es una cadena entera: RUB y XTR usan 1000 unidades, USD 1.000.000. El monto saliente y el pago son cadenas decimales en sus monedas.

Keitaro recibe un tid estable por objetivo y evento, por lo que los reintentos no agregan otra conversión. En Binom, reserve evento1…evento24 y una moneda de pago, RUB o USD. El adaptador envía valores absolutos de eventos e ingresos acumulativos con enable_upsell=1 y enable_postback=1. No los vuelvas a agregar en las reglas de tu rastreador.

Punto final personalizado: GET o POST

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

Las macros solo se permiten en los valores de consulta: tracker_click_id, click_id, event_id, goal_id, event, link_id, sub_id_1…sub_id_5, monto, moneda, pago, moneda_pago y ocurrió_at. Envuelva los nombres de las macros entre llaves. status, objetivo y cantidad menor no son macros. event_id y tracker_click_id se agregan a las solicitudes GET personalizadas incluso cuando se omiten en su plantilla.

POST envía JSON fijo con esos campos más esquema_version=1, test_mode, event_type y corrects_event_id; no es una plantilla de cuerpo personalizada. Almacene event_id con una restricción ÚNICA en la misma transacción que se procesa y devuelva 2xx para duplicados. Un event_type=correction hace referencia a su evento original a través de corrects_event_id. Nunca dé crédito a usuarios reales por eventos test_mode=true.

Entrega, reintentos y diario

La vista previa no envía ninguna solicitud. Una prueba de entrega utiliza un ID sintético de px_test_…; HTTP 2xx demuestra solo una respuesta de punto final, no una conversión de rastreador. Para una verificación de extremo a extremo, siga el enlace de su rastreador y alcance una meta. El diario muestra el evento, el estado y el motivo del error mientras enmascara los parámetros secretos.

Las fallas de red, 429 y 5xx se reintentan con retroceso, hasta 8 intentos automáticos por ciclo. Otros 4xx y redirecciones detienen la entrega. El reintento manual mantiene el event_id, la URL y la carga útil originales. Un evento fallido bloquea eventos posteriores para ese clic externo: restaure el punto final y vuelva a intentarlo. Los cambios de configuración se aplican a visitas futuras sin reenviar el historial. Se conserva la atribución de referencia original.

Gestión API: /api/v1/referrals/postbacks, solo propietario autenticado. GET listas y POST crea; /{id} admite GET y PUT; /{id}/events es el diario; /preview y /{id}/preview procesan una solicitud; /{id}/test y /events/{event_id}/retry entregan explícitamente. Crear, guardar, probar y reintentar requiere Idempotency-Key (de 1 a 96 caracteres); las actualizaciones necesitan la versión actual. La clave del editor X-PixorAds no se utiliza aquí.