anyads 0.1.3

Official SDK for the AnyAds advertising platform for Telegram bots.

Официальный Python SDK для легкой интеграции вашего Telegram-бота с рекламной платформой AnyAds.online. Начните монетизировать вашу аудиторию уже сегодня!

🚀 Быстрый старт

Этот гайд поможет вам интегрировать SDK и подготовить вашего бота к заработку менее чем за 5 минут.

Шаг 1: Установка

Установите пакет, используя pip. Если вы работаете с фреймворком Aiogram, мы настоятельно рекомендуем установить SDK с дополнительными зависимостями для упрощенной интеграции.

# Для Aiogram
pip install "anyads[aiogram]"

# Стандартная установка (для других фреймворков)
pip install anyads

Шаг 2: Получение API Key

1. Зарегистрируйтесь на anyads.online.
2. Перейдите в раздел "Площадки" и добавьте вашего бота, указав его @username.
3. Для вашей новой площадки будет сгенерирован уникальный API_KEY, начинающийся с anyads_.... Скопируйте его. Он понадобится на следующем шаге.

Шаг 3: Интеграция в код (Пример для Aiogram 3.x)

В главном файле вашего бота, где происходит его запуск, добавьте следующий код:

import asyncio
import os
import logging
from aiogram import Bot, Dispatcher, types

# 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)

# --- Инициализация Aiogram ---
dp = Dispatcher()
bot = Bot(TELEGRAM_BOT_TOKEN)

# 2. Инициализируем SDK AnyAds
# SDK автоматически запустит фоновый опрос рекламных задач
sdk = anyads.init(api_key=ANYADS_API_KEY)

# 3. Регистрируем обработчики AnyAds, используя импортированный модуль
aiogram_handlers.register(dp)


# 4. Создаем обработчик для полученной рекламы
@sdk.on_broadcast_received
async def handle_ad_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

        # Собираем инлайн-клавиатуру
        keyboard_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:
                    keyboard_builder.row(*buttons)

        reply_markup = keyboard_builder.as_markup() if buttons_data else None

        # !!! ВАЖНО: Здесь ваша логика получения списка ID пользователей
        user_ids = [] # Заглушка, замените на реальный код

        for user_id in user_ids:
            try:
                # Отправляем сообщение. Логика простая, т.к. Ad Engine
                # присылает уже валидные данные.
                if image_url:
                    await bot.send_photo(
                        user_id,
                        photo=image_url,
                        caption=(text or ''),
                        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_ad_task: {e}", exc_info=True)


# --- Основная функция запуска ---
async def main():
    # Запускаем фоновый опрос AnyAds
    await sdk.start()

    # Запускаем бота
    try:
        await dp.start_polling(bot)
    finally:
        # Корректно останавливаем SDK при завершении работы бота
        await sdk.stop()
        logging.info("Бот и AnyAds SDK остановлены.")

if __name__ == "__main__":
    if not ANYADS_API_KEY or not TELEGRAM_BOT_TOKEN:
        raise RuntimeError("Необходимо установить переменные окружения ANYADS_API_KEY и TELEGRAM_BOT_TOKEN")

    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Бот остановлен вручную.")

4. Верификация

После того как вы запустите бота с интегрированным SDK, его статус в личном кабинете AnyAds.online будет "Ожидает верификации". Наша команда модераторов проверит интеграцию и активирует вашу площадку. После этого ваш бот начнет получать рекламные задачи.

⚙️ Универсальная интеграция (для других фреймворков)

Если вы не используете aiogram, вы можете легко интегрировать SDK вручную.

1. Установите ядро SDK: pip install anyads
2. Инициализируйте и запустите SDK, как в примере выше (anyads.init(...), await sdk.start()).
3. Обработайте команду верификации: Вам нужно самостоятельно поймать сообщение, начинающееся с /verify_anyads_, и передать его в SDK.

# Пример обработчика
async def handle_messages(message):
    if message.text and message.text.startswith('/verify_anyads_'):
        sdk = anyads.get_sdk_instance()
        success = await sdk.process_verification_code(message.text)
        if success:
            # Ответить пользователю об успехе
            pass

❓ Нужна помощь?

Если у вас возникли вопросы, обратитесь в нашу поддержку или изучите полную документацию на docs.anyads.online.