Официальный Python SDK для легкой интеграции вашего Telegram-бота с рекламной платформой AnyAds.online.
Вы можете установить наш SDK двумя способами: напрямую через командную строку или добавив его в файл зависимостей вашего проекта.
pip (Рекомендуется для быстрой пробы)Выполните команду в вашем терминале. Этот способ идеально подходит, чтобы быстро попробовать наш SDK.
Стандартная установка:
pip install anyads
Установка с поддержкой aiogram:
pip install "anyads[aiogram]"
Подсказка: Использование
[aiogram]автоматически установит библиотекуaiogramи позволит вам использовать наши готовые функции-хелперы для этого фреймворка.
requirements.txt (Рекомендуется для проектов)Если вы уже работаете над проектом, лучшей практикой является добавление anyads в ваш файл requirements.txt. Это гарантирует, что все разработчики в вашей команде и ваша система развертывания (CI/CD, Docker) будут использовать одну и ту же версию.
Откройте ваш файл requirements.txt.
Добавьте одну из следующих строк в конец файла:
# requirements.txt
# --- Добавьте эту строку для стандартной установки ---
anyads==1.1.0
# --- ИЛИ эту, если вы используете aiogram ---
anyads[aiogram]==1.1.0
Примечание: Мы настоятельно рекомендуем указывать конкретную версию (
==1.1.0), чтобы избежать неожиданных обновлений. Актуальную версию всегда можно найти на странице пакета в PyPI.
Установите или обновите все зависимости из файла:
pip install -r requirements.txt
Наш SDK имеет модульную структуру. После инициализации вы получаете доступ к двум основным "обработчикам", каждый из которых отвечает за свой тип монетизации:
sdk.posts: Управляет рекламными рассылками (Newsletters). Работает в режиме фонового опроса (polling).sdk.tasks: Управляет заданиями на подписку (Subscription Tasks). Работает в режиме "по требованию" (on-demand).Вы можете использовать оба типа монетизации одновременно или только один из них.
Этот модуль позволяет вашему боту автоматически получать и рассылать рекламные объявления по вашей базе пользователей.
Шаг 1: Инициализация и регистрация обработчиков
В главном файле вашего бота импортируйте и настройте SDK.
import asyncio
import os
import logging
from aiogram import Bot, Dispatcher
# 1. Импортируем AnyAds и хелперы для aiogram
import anyads
from anyads.integrations import aiogram_handlers
# --- Конфигурация ---
ANYADS_API_KEY = os.getenv("ANYADS_API_KEY")
TELEGRAM_BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
logging.basicConfig(level=logging.INFO)
# --- Инициализация ---
dp = Dispatcher()
bot = Bot(TELEGRAM_BOT_TOKEN)
# 2. Инициализируем SDK
sdk = anyads.init(api_key=ANYADS_API_KEY)
# 3. Регистрируем обработчик для верификации
aiogram_handlers.register(dp)
Шаг 2: Создание обработчика для рассылки
Используйте декоратор @sdk.posts.on_broadcast_received, чтобы пометить вашу функцию, которая будет выполнять рассылку. SDK вызовет ее автоматически, когда получит задачу.
from aiogram.utils.keyboard import InlineKeyboardBuilder
from aiogram import types
# Лимиты Telegram API
CAPTION_MAX_LENGTH = 1024
MESSAGE_MAX_LENGTH = 4096
@sdk.posts.on_broadcast_received
async def handle_newsletter_task(task_data: dict):
"""
Эта функция будет вызвана SDK для обработки новой задачи на рассылку.
"""
logging.info(f"Получена задача на рассылку: {task_data.get('task_id')}")
try:
creative = task_data.get("creative", {})
content = creative.get("content", {})
text = content.get("text")
files = content.get("files", [])
buttons_data = content.get("buttons", [])
image_url = files[0] if files else None
if not text and not image_url:
logging.error("Креатив пуст. Задача проигнорирована.")
return
# Собираем инлайн-клавиатуру
builder = InlineKeyboardBuilder()
if buttons_data:
for row in buttons_data:
buttons = [types.InlineKeyboardButton(text=btn['text'], url=btn['url']) for btn in row]
if buttons:
builder.row(*buttons)
reply_markup = builder.as_markup() if buttons_data else None
# !!! ВАЖНО: Здесь ваша логика получения списка ID пользователей
user_ids = [] # user_ids = await get_all_active_users_from_your_database()
for user_id in user_ids:
try:
if image_url:
await bot.send_photo(user_id, photo=image_url, caption=text, reply_markup=reply_markup)
elif text:
await bot.send_message(user_id, text=text, reply_markup=reply_markup, disable_web_page_preview=True)
await asyncio.sleep(0.05) # Пауза для обхода лимитов на скорость
except Exception as e:
logging.warning(f"Не удалось отправить сообщение пользователю {user_id}: {e}")
except Exception as e:
logging.error(f"Критическая ошибка в обработчике handle_newsletter_task: {e}", exc_info=True)
# --- Запуск ---
async def main():
await sdk.start() # Запускает фоновые процессы SDK
await dp.start_polling(bot)
await sdk.stop() # Корректная остановка
Этот модуль позволяет блокировать доступ к функционалу вашего бота до тех пор, пока пользователь не подпишется на предложенные каналы.
Мы предоставляем готовые UI-хелперы, которые берут на себя всю работу по отображению заданий и проверке подписки.
Шаг 1: Импортируйте UI-хелперы
from anyads.integrations import aiogram_ui, aiogram_handlers
Шаг 2: Определите функции-коллбэки
Вам нужно создать две функции:
on_success: Что делать, когда пользователь успешно выполнил задание.fallback_handler: Что делать, если для пользователя нет доступных заданий.# Эта функция покажет основное меню после успешной подписки
async def show_main_menu(query: types.CallbackQuery):
await query.message.answer("Спасибо! Вот наше главное меню:")
# ... ваш код для показа основного меню ...
# Эта функция покажет обычное приветствие, если заданий нет
async def show_welcome_message(message: types.Message):
await message.answer("Добро пожаловать в нашего супер-бота!")
Шаг 3: Зарегистрируйте обработчики и используйте хелпер
from aiogram.filters import CommandStart
# Регистрируем UI-обработчики, передавая наш коллбэк on_success
aiogram_ui.register_ui_handlers(dp, bot, on_success=show_main_menu)
@dp.message(CommandStart())
async def handle_start(message: types.Message, bot: Bot):
# Вызываем главный хелпер. Он сделает всё сам.
# В fallback_handler передаем нашу функцию-приветствие.
await aiogram_ui.handle_start_with_task(
message,
bot,
fallback_handler=lambda: show_welcome_message(message)
)
Если вы хотите полностью кастомизировать сообщения, вы можете использовать низкоуровневые методы SDK.
@dp.message(CommandStart())
async def handle_start_manual(message: types.Message):
sdk = anyads.get_sdk_instance()
user_id = message.from_user.id
loading_msg = await message.answer("Загрузка...")
# 1. Запрашиваем задание
task = await sdk.tasks.get_subscription_task(user_id)
if task:
# 2. Если есть - самостоятельно формируем и отправляем сообщение
# с кнопкой, содержащей task['execution_id']
execution_id = task['execution_id']
# ... ваш код для отображения каналов и кнопки ...
else:
# 3. Показываем свое приветствие
await loading_msg.edit_text("Добро пожаловать!")
# Вам также нужно будет самостоятельно написать обработчик для коллбэка
# и вызвать в нем `await sdk.tasks.complete_subscription_task(execution_id, user_id)`
anyads.init(api_key: str, interval_seconds: int = 300): Инициализирует SDK. interval_seconds влияет только на частоту опроса рассылок.await sdk.start(): Запускает все фоновые процессы SDK.await sdk.stop(): Корректно останавливает SDK.await sdk.process_verification_code(code: str): Обрабатывает команду верификации.sdk.posts)@sdk.posts.on_broadcast_received: Декоратор для регистрации коллбэка для рассылок.sdk.tasks)await sdk.tasks.get_subscription_task(user_id: int): Запрашивает задание на подписку. Возвращает dict или None.await sdk.tasks.complete_subscription_task(execution_id: int, user_id: int): Инициирует проверку подписки. Возвращает bool.