nativeads 0.1.0

NativeAds SDK for Telegram bots — inject ads into LLM replies (aiogram / python-telegram-bot / raw).

nativeads (Python)

Python SDK for NativeAds — monetize your Telegram bot by injecting ads into LLM replies. Works with aiogram 3.x, python-telegram-bot v20+, or raw bot code.

pip install nativeads              # core (httpx only)
pip install nativeads[aiogram]     # + aiogram 3.x
pip install nativeads[ptb]         # + python-telegram-bot v20+

Quick start (inject)

from nativeads import NativeAds

ads = NativeAds(api_key="sk_live_xxx", platform_id="plt_xxx")

# inside an async message handler, after generating the LLM answer:
result = await ads.inject(
    user_id=message.from_user.id,
    message=llm_answer,
    language_code=message.from_user.language_code,
    is_premium=message.from_user.is_premium,
    keyboard=my_keyboard,        # optional — aiogram / PTB / raw dict
    # ad_button_position="top",  # default "bottom"
)
await message.answer(result.message, reply_markup=result.keyboard)

aiogram middleware (DI)

from nativeads import NativeAds
from nativeads.middleware import NativeAdsMiddleware

mw = NativeAdsMiddleware(api_key="sk_live_xxx", platform_id="plt_xxx")
dp.message.middleware(mw)
dp.shutdown.register(mw.aclose)

async def handler(message: Message, nativeads: NativeAds):
    result = await nativeads.inject(user_id=message.from_user.id, message=answer)
    await message.answer(result.message, reply_markup=result.keyboard)

Privacy-friendly mode (fetch)

res = await ads.fetch(user_id=uid, language_code="ru")
if res.has_ad:
    text = f"{llm_answer}\n\n{res.ad.ad_text}"
    # render res.ad.button_text / res.ad.button_url yourself

Guarantees

• Never raises. On any error (timeout, network, 5xx) inject()/fetch() return your original message and keyboard unchanged. Default timeout 3s.
• Your buttons are preserved — the ad button is a separate row (top/bottom), respecting Telegram's 4096-char and 13-row limits.
• Click tracking is automatic — button_url is a tracking redirect.

API

• NativeAds(api_key, platform_id=None, *, base_url=..., timeout=3.0, platform="telegram", show_every=1, skip_first=0)
  • show_every — ad on every Nth message (5 = optimal, 0 = off); N>1 keeps the first message ad-free.
  • skip_first — never show an ad on a user's first N messages.
  • Frequency is client-side (in-memory per-user counter); skipped turns return your message without a server call.
  • NativeAdsMiddleware(...) accepts the same show_every / skip_first.
• await ads.inject(*, user_id, message, language_code=None, is_premium=None, keyboard=None, ad_button_position="bottom", parse_mode=None) -> InjectResult
• await ads.fetch(*, user_id, language_code=None, is_premium=None, parse_mode=None) -> FetchResult
• await ads.aclose()

InjectResult(message, has_ad, impression_id, ad, keyboard) · FetchResult(has_ad, impression_id, ad) · Ad(ad_text, button_text, button_url, ad_text_formatted)