Meta reklama (Marketing API) Python SDK ma'lumotnomasi

Klientni muhit o'zgaruvchilaridan yaratadi: FACEBOOK_APP_SECRET (appsecret_proof uchun) va META_GRAPH_VERSION. Qo'shimcha argumentlar (timeout, retry, session, license_key) konstruktorga uzatiladi.

Ads.from_env(**kwargs) -> Ads

• ▸Boshqa klientlardan farqli o'laroq bo'sh kalitda xato bermaydi: FACEBOOK_APP_SECRET bo'lmasa app_secret bo'sh qoladi va so'rovlarga appsecret_proof qo'shilmaydi. Meta app sozlamalarida app secret talab qilinsa, bunday so'rovlar rad etiladi.
• ▸META_GRAPH_VERSION berilmasa SDK'dagi standart versiya ishlatiladi; kerakli versiyani Ads.from_env(graph_version="...") bilan ustidan yozish mumkin.
• ▸Access token bu yerda o'qilmaydi — u har bir metodga argument bo'lib beriladi.

Foydalanuvchi token'i kira oladigan reklama kabinetlarini id, name, currency va holati bilan AdAccount ro'yxati sifatida qaytaradi. Odatda birinchi chaqiruv: boshqa metodlarning ko'pchiligiga ad_account_id kerak.

await ads.ad_accounts(token: str) -> list[socialift.ads.AdAccount]

• ▸Foydalanuvchi access token'i (Page token emas) va ads_read kerak.
• ▸Bitta sahifa, 50 tagacha kabinet qaytadi.
• ▸is_active Meta'ning account_status qiymati 1 bo'lganda True.
• ▸Byudjetlar kabinet valyutasida (currency); UZS Meta'ning reklama kabineti valyutalari ro'yxatida yo'q.

Kerakli ruxsatlar:ads_read

for account in await ads.ad_accounts(user_token):
    print(account.id, account.currency)

Reklama kabinetiga ulangan Meta piksellarini last_fired_time bilan qaytaradi. Konversiya ad set'lari (promoted_object) va sayt auditoriyalari uchun piksel ID'si kerak bo'ladi.

await ads.pixels(token: str, *, ad_account_id: str) -> list[dict]

• ▸Bitta sahifa, 50 tagacha piksel; ads_read kerak.

Kerakli ruxsatlar:ads_read

pixels = await ads.pixels(user_token, ad_account_id="act_123")

Oddiy argumentlardan Meta targeting spetsifikatsiyasini (dict) yig'adi: joylashuv, yosh, jins, til, qiziqish, xatti-harakat, custom auditoriyalar, joylashuvlar (placements). Sof funksiya: tarmoq so'rovi ham, token ham yo'q.

Ads.build_targeting(
    *,
    countries: Optional[list[str]] = None,
    regions: Optional[list[Any]] = None,
    cities: Optional[list[Any]] = None,
    zips: Optional[list[Any]] = None,
    excluded_countries: Optional[list[str]] = None,
    excluded_cities: Optional[list[Any]] = None,
    age_min: Optional[int] = None,
    age_max: Optional[int] = None,
    genders: Optional[list[Any]] = None,
    locales: Optional[list[int]] = None,
    interests: Optional[list[Any]] = None,
    behaviors: Optional[list[Any]] = None,
    demographics: Optional[list[Any]] = None,
    life_events: Optional[list[Any]] = None,
    excluded_interests: Optional[list[Any]] = None,
    custom_audiences: Optional[list[str]] = None,
    excluded_custom_audiences: Optional[list[str]] = None,
    platforms: Optional[list[str]] = None,
    facebook_positions: Optional[list[str]] = None,
    instagram_positions: Optional[list[str]] = None,
    devices: Optional[list[str]] = None,
    connections: Optional[list[str]] = None,
    excluded_connections: Optional[list[str]] = None,
    flexible_spec: Optional[list[dict]] = None,
    advantage_audience: bool = True,
) -> dict[str, Any]

• ▸interests ichidagi elementlar YOKI bilan birlashadi; "VA" kerak bo'lsa flexible_spec bering — uning har bir elementi alohida VA sharti.
• ▸genders 1/2 yoki "male"/"female" qabul qiladi; hammani nishonga olish uchun umuman bermang. Yosh 13–65 oralig'iga keltiriladi.
• ▸advantage_audience standart True. Advantage+ audience yoqilganda Meta age_max ni 65 ga qotiradi va age_min ni faqat 18–25 oralig'ida qabul qiladi — qat'iy yosh chegarasi uchun advantage_audience=False bering.
• ▸Meta ad set targeting'ida joylashuvni talab qiladi; bu yordamchi buni tekshirmaydi, shuning uchun countries, regions, cities yoki zips bering.

targeting = ads.build_targeting(countries=["UZ"], age_min=18, age_max=45, interests=[{"id": "6003107902433"}], advantage_audience=False)

Targeting spetsifikatsiyasi va optimizatsiya maqsadi uchun auditoriya hajmini hech narsa yaratmasdan va pul sarflamasdan baholaydi. Juda kichik yoki juda keng auditoriyani ad set yaratishdan oldin aniqlash uchun.

await ads.delivery_estimate(
    token: str,
    *,
    ad_account_id: str,
    targeting: dict[str, Any],
    optimization_goal: str = 'REACH',
    promoted_object: Optional[dict] = None,
) -> dict

• ▸Faqat o'qish: hech narsa yaratilmaydi, hech narsa hisobga yozilmaydi.
• ▸Meta javobidagi birinchi baholash qatorini dict sifatida qaytaradi (bo'lmasa bo'sh dict).
• ▸optimization_goal standarti REACH; ad set uchun rejalashtirgan maqsadni bering.
• ▸ads_read kerak.

Kerakli ruxsatlar:ads_read

estimate = await ads.delivery_estimate(user_token, ad_account_id="act_123", targeting=targeting)

Meta qiziqish (interest) targeting variantlarini nom bo'yicha qidiradi: id, name, auditoriya hajmi chegaralari va path qaytadi. ID'larni build_targeting(interests=...) da ishlating.

await ads.search_interests(token: str, query: str, *, limit: int = 25) -> list[dict]

• ▸limit standarti 25; ads_read kerak.
• ▸Meta qiziqishlarni vaqt o'tishi bilan eskirgan deb belgilaydi — saqlangan ID'larni validate_targeting() bilan tekshiring.

Kerakli ruxsatlar:ads_read

interests = await ads.search_interests(user_token, "fitness", limit=25)
cities = await ads.search_locations(user_token, "Tosh", country_code="UZ")

Meta til (locale) targeting variantlarini qidiradi va build_targeting(locales=...) uchun raqamli kalitlarni qaytaradi. Auditoriyani joylashuv emas, til bo'yicha ajratish kerak bo'lganda ishlating.

await ads.search_locales(token: str, query: str, *, limit: int = 25) -> list[dict]

Meta joylashuvlarini (davlat, viloyat, shahar) nom bo'yicha qidiradi; javobdagi key targeting kutadigan identifikator. Natijani country_code bilan toraytiring.

await ads.search_locations(
    token: str,
    query: str,
    *,
    location_types: tuple[str, ...] = ('city', 'region', 'country'),
    country_code: Optional[str] = None,
    limit: int = 25,
) -> list[dict]

• ▸location_types standarti: city, region, country; pochta indekslari uchun zip qo'shing.
• ▸Shaharga radius berish mumkin: {"key": "...", "radius": 25, "distance_unit": "kilometer"}; Meta 17–80 km (10–50 mil) oralig'ini qabul qiladi.
• ▸ads_read kerak.

Kerakli ruxsatlar:ads_read

interests = await ads.search_interests(user_token, "fitness", limit=25)
cities = await ads.search_locations(user_token, "Tosh", country_code="UZ")

Bitta sinfdagi targeting kategoriyalarini ro'yxatlaydi yoki qidiradi: behaviors, demographics, life_events, industries, income va boshqalar. query bo'lmasa butun sinf qaytadi — masalan, tanlash ro'yxatini yasash uchun.

await ads.search_targeting(
    token: str,
    *,
    target_class: str = 'interests',
    query: Optional[str] = None,
    limit: int = 50,
) -> list[dict]

• ▸target_class TARGETING_CLASSES dan biri bo'lishi kerak, aks holda so'rovdan oldin ConfigurationError.

Berilgan targeting variantlariga o'xshashlarini (masalan, yaqin qiziqishlarni) taklif qiladi. Juda tor chiqqan auditoriyani kengaytirishning tez yo'li.

await ads.targeting_suggestions(
    token: str,
    *,
    ad_account_id: str,
    targeting_list: list[dict],
    limit: int = 25,
) -> list[dict]

• ▸targeting_list formati: [{"type": "interests", "id": "..."}]; ads_read kerak.

Kerakli ruxsatlar:ads_read

similar = await ads.targeting_suggestions(user_token, ad_account_id="act_123", targeting_list=[{"type": "interests", "id": "6003107902433"}])

Saqlangan targeting elementlari (qiziqish ID'lari va boshqalar) shu kabinet uchun hali yaroqli ekanini tekshiradi. Eski targeting'ni yangi ad set'da qayta ishlatishdan oldin chaqiring.

await ads.validate_targeting(
    token: str,
    *,
    ad_account_id: str,
    targeting_list: list[dict],
) -> list[dict]

• ▸Meta targeting variantlarini vaqt o'tishi bilan eskirgan deb chiqaradi, shuning uchun oylar oldin saqlangan ID endi ishlamasligi mumkin.
• ▸ads_read kerak.

Kerakli ruxsatlar:ads_read

result = await ads.validate_targeting(user_token, ad_account_id="act_123", targeting_list=[{"type": "interests", "id": "6003107902433"}])

Reklamalarni kreativi, holati va oldindan ko'rish havolasi bilan qaytaradi — bitta ad set, bitta kampaniya yoki butun kabinet bo'yicha.

await ads.ads(
    token: str,
    *,
    ad_account_id: Optional[str] = None,
    adset_id: Optional[str] = None,
    campaign_id: Optional[str] = None,
    limit: int = 100,
) -> list[dict]

• ▸Ustuvorlik: adset_id, keyin campaign_id, keyin ad_account_id; hech biri bo'lmasa ConfigurationError.
• ▸limit gacha bitta sahifa; ads_read kerak.

Kerakli ruxsatlar:ads_read

items = await ads.ads(user_token, adset_id="120200000000001")

Bitta ad set'ni ID bo'yicha targeting, byudjetlar, bid, optimizatsiya maqsadi va jadvali bilan oladi.

await ads.adset(token: str, adset_id: str) -> dict

Kampaniyaning (campaign_id) yoki butun reklama kabinetining (ad_account_id) ad set'larini targeting, byudjet va optimizatsiya maydonlari bilan qaytaradi.

await ads.adsets(
    token: str,
    *,
    ad_account_id: Optional[str] = None,
    campaign_id: Optional[str] = None,
    limit: int = 100,
) -> list[dict]

• ▸Ikkalasi berilsa campaign_id ustun; hech biri berilmasa ConfigurationError.
• ▸limit (standart 100) gacha bitta sahifa; ads_read kerak.

Kerakli ruxsatlar:ads_read

adsets = await ads.adsets(user_token, campaign_id="120200000000000")

Mavjud Instagram postini bitta chaqiruvda reklamaga aylantiradi: kampaniya, ad set, postdan kreativ va reklamani yaratadi — hammasi PAUSED. ID'larini qaytaradi; set_status(..., "ACTIVE") chaqirilmaguncha pul sarflanmaydi.

await ads.boost_post(
    token: str,
    *,
    ad_account_id: str,
    ig_user_id: str,
    media_id: str,
    name: str,
    daily_budget_major: float,
    goal: str = 'traffic',
    page_id: Optional[str] = None,
    link: Optional[str] = None,
    targeting: Optional[dict[str, Any]] = None,
    currency: Optional[str] = None,
    cleanup_on_error: bool = True,
) -> dict[str, str]

• ▸goal: traffic, engagement, reach yoki messages (OUTCOME_* maqsad va optimizatsiyaga moslanadi); messages uchun page_id majburiy. Kampaniya bo'sh special_ad_categories bilan yaratiladi — uy-joy, ish, moliya yoki siyosat reklamasi uchun ishlatmang.
• ▸daily_budget_major kabinet valyutasida va CURRENCY_OFFSET (100) ga ko'paytiriladi; Meta offset 1 ishlatadigan valyutalarda (JPY, KRW, IDR, VND, HUF ...) summani avval 100 ga bo'ling.
• ▸targeting berilmasa default_targeting() ishlatiladi: UZ, 18–55 yosh, Instagram joylashuvlari, Advantage+ audience yoqilgan.
• ▸To'rt obyekt ketma-ket yaratiladi: keyingi qadam xato bersa, oldingilari kabinetda (PAUSED) qoladi — ularni o'chiring. Mualliflik huquqi bilan himoyalangan musiqa yoki filtr kabi interaktiv elementli postni ko'tarib bo'lmaydi.

Kerakli ruxsatlar:ads_managementinstagram_basic

result = await ads.boost_post(user_token, ad_account_id="act_123", ig_user_id="1784...", media_id="1790...", name="Reels boost", daily_budget_major=10, goal="traffic")

Bitta kampaniyani ID bo'yicha campaigns() dagi maydonlar bilan oladi: maqsad, holat, byudjetlar, bid strategiyasi, maxsus reklama kategoriyalari.

await ads.campaign(token: str, campaign_id: str) -> dict

Reklama kabinetidagi kampaniyalarni byudjet, maqsad va holat maydonlari bilan qaytaradi. statuses bilan filtrlang, masalan ["ACTIVE", "PAUSED"].

await ads.campaigns(
    token: str,
    *,
    ad_account_id: str,
    statuses: Optional[list[str]] = None,
    limit: int = 100,
) -> list[dict]

• ▸statuses Meta'ga effective_status filtri sifatida yuboriladi.
• ▸limit (standart 100) gacha bitta sahifa qaytadi, avtomatik sahifalash yo'q.
• ▸ads_read kerak.

Kerakli ruxsatlar:ads_read

campaigns = await ads.campaigns(user_token, ad_account_id="act_123", statuses=["ACTIVE", "PAUSED"])

Ad set ichida tayyor creative_id yoki ichma-ich creative spetsifikatsiyasidan reklama yaratadi. Standart holatda PAUSED.

await ads.create_ad(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    adset_id: str,
    creative_id: Optional[str] = None,
    creative: Optional[dict] = None,
    status: str = 'PAUSED',
    **extra: Any,
) -> dict

• ▸creative_id yoki creative dan biri kerak; ikkalasi berilsa creative_id ishlatiladi.
• ▸Qo'shimcha Meta maydonlari **extra orqali satr yoki son sifatida beriladi (dict'larni o'zingiz JSON qiling).

Kerakli ruxsatlar:ads_management

ad = await ads.create_ad(user_token, ad_account_id="act_123", name="Banner A", adset_id="120200000000001", creative_id="120200000000002")

Ad set yaratadi: reklamani kim ko'radi (targeting), qanday optimizatsiya qilinadi va — kampaniyada byudjet bo'lmasa — qancha sarflanadi. Standart holatda PAUSED yaratiladi.

await ads.create_adset(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    campaign_id: str,
    targeting: dict[str, Any],
    optimization_goal: str = 'LINK_CLICKS',
    billing_event: str = 'IMPRESSIONS',
    status: str = 'PAUSED',
    daily_budget_major: Optional[float] = None,
    lifetime_budget_major: Optional[float] = None,
    bid_amount_major: Optional[float] = None,
    start_time: Optional[str] = None,
    end_time: Optional[str] = None,
    promoted_object: Optional[dict] = None,
    destination_type: Optional[str] = None,
    currency: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸targeting bo'sh bo'lmasligi kerak — build_targeting() yoki default_targeting() bilan yig'ing. optimization_goal va billing_event OPTIMIZATION_GOALS va BILLING_EVENTS bo'yicha tekshiriladi.
• ▸daily_budget_major, lifetime_budget_major va bid_amount_major CURRENCY_OFFSET (100) ga ko'paytiriladi; offset 1 valyutalarda (JPY, KRW, IDR, VND, HUF ...) avval 100 ga bo'ling.
• ▸lifetime_budget_major bilan end_time majburiy. Yaratishda Meta faqat ACTIVE yoki PAUSED holatini qabul qiladi.
• ▸Ba'zi maqsadlar promoted_object ni talab qiladi, masalan konversiyalar uchun {"pixel_id": "...", "custom_event_type": "PURCHASE"}.

Kerakli ruxsatlar:ads_management

adset = await ads.create_adset(user_token, ad_account_id="act_123", name="Toshkent 18-45", campaign_id="120200000000000", targeting=targeting, daily_budget_major=15)

Kampaniya yaratadi — maqsadni va ixtiyoriy ravishda kampaniya byudjetini belgilaydigan yuqori qavat. Standart holatda PAUSED yaratiladi.

await ads.create_campaign(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    objective: str = 'OUTCOME_TRAFFIC',
    status: str = 'PAUSED',
    daily_budget_major: Optional[float] = None,
    lifetime_budget_major: Optional[float] = None,
    bid_strategy: Optional[str] = None,
    special_ad_categories: Optional[list[str]] = None,
    special_ad_category_country: Optional[list[str]] = None,
    is_adset_budget_sharing_enabled: Optional[bool] = None,
    currency: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸objective OBJECTIVES dagi OUTCOME_* qiymatlardan biri bo'lishi kerak; eski nomlar ConfigurationError beradi.
• ▸special_ad_categories har doim yuboriladi (berilmasa bo'sh ro'yxat): Meta har bir kampaniyadan kategoriyani e'lon qilishni talab qiladi, masalan HOUSING, EMPLOYMENT, FINANCIAL_PRODUCTS_SERVICES, ISSUES_ELECTIONS_POLITICS.
• ▸Byudjet yo shu yerda (daily_budget_major yoki lifetime_budget_major, bittasi), yo ad set'larda beriladi, ikkalasida emas. Summa CURRENCY_OFFSET (100) ga ko'paytiriladi — JPY, KRW kabi offset 1 valyutalarda avval 100 ga bo'ling.
• ▸Marketing API v24.0 dan boshlab o'z byudjeti yo'q kampaniya is_adset_budget_sharing_enabled ni talab qiladi; uni **extra orqali satr ko'rinishida bering ("false" yoki "true").

Kerakli ruxsatlar:ads_management

campaign = await ads.create_campaign(user_token, ad_account_id="act_123", name="Kuz aksiyasi", objective="OUTCOME_TRAFFIC", daily_budget_major=20)

Kampaniya, ad set, reklama yoki boshqa Marketing API obyektini ID bo'yicha HTTP DELETE bilan o'chiradi. Sarfni to'xtatib, obyektni saqlab qolish uchun set_status(..., "PAUSED") ishlating.

await ads.delete(token: str, node_id: str) -> bool

• ▸Meta'ning success belgisini qaytaradi; ads_management kerak.

Kerakli ruxsatlar:ads_management

await ads.delete(user_token, node_id)

Kampaniya, ad set yoki reklama holatini o'zgartiradi. ACTIVE sarfni boshlaydi; PAUSED ko'rsatishni to'xtatadi va reklamani o'chirishning xavfsiz usuli.

await ads.set_status(token: str, node_id: str, status: str) -> bool

• ▸Qabul qilinadigan qiymatlar: ACTIVE, PAUSED, ARCHIVED, DELETED; boshqasi ConfigurationError.
• ▸Kampaniya yoki ad set to'xtatilgan bo'lsa, ichidagi reklamaning effektiv holati CAMPAIGN_PAUSED yoki ADSET_PAUSED bo'ladi.
• ▸ads_management kerak.

Kerakli ruxsatlar:ads_management

await ads.set_status(user_token, campaign_id, "ACTIVE")

Ad set'ga yangi kunlik byudjet o'rnatadi. Ishlab turgan reklamaga darhol ta'sir qiladi, shuning uchun summani ikki marta tekshiring.

await ads.update_budget(
    token: str,
    adset_id: str,
    daily_budget_major: float,
    *,
    currency: Optional[str] = None,
    ad_account_id: Optional[str] = None,
) -> bool

• ▸daily_budget_major noldan katta bo'lishi kerak va CURRENCY_OFFSET (100) ga ko'paytiriladi; offset 1 valyutalarda avval 100 ga bo'ling.
• ▸ads_management kerak.

Kerakli ruxsatlar:ads_management

await ads.update_budget(user_token, adset_id, daily_budget_major=25)

Mavjud ad set targeting'ini berilgan spetsifikatsiya bilan almashtiradi. O'zgarish emas, to'liq yangi spetsifikatsiyani bering.

await ads.update_targeting(token: str, adset_id: str, targeting: dict[str, Any]) -> bool

• ▸Bo'sh targeting ConfigurationError beradi; ads_management kerak.
• ▸Advantage+ audience yosh qoidalari bu yerda ham amal qiladi (build_targeting() ga qarang).

Kerakli ruxsatlar:ads_management

await ads.update_targeting(user_token, adset_id, targeting)

Page, havola, matn va yuklangan rasm (image_hash) yoki video (video_id) dan havolali reklama kreativini yaratadi. Mavjud post emas (boost_post()), reklama uchun alohida kreativ kerak bo'lganda ishlating.

await ads.create_creative(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    page_id: str,
    link: str,
    message: Optional[str] = None,
    headline: Optional[str] = None,
    description: Optional[str] = None,
    image_hash: Optional[str] = None,
    video_id: Optional[str] = None,
    call_to_action: str = 'LEARN_MORE',
    instagram_user_id: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸SDK object_story_spec.link_data ni yig'adi: headline — name ga, call_to_action (standart LEARN_MORE) — type ga tushadi.
• ▸Reklama Instagram akkaunti nomidan chiqishi uchun instagram_user_id bering; page_id har doim majburiy.
• ▸image_hash ni upload_image() dan oling. ads_management kerak.

Kerakli ruxsatlar:ads_management

creative = await ads.create_creative(user_token, ad_account_id="act_123", name="Kuz", page_id="1111", link="https://siz.uz", message="Chegirma 30%", image_hash=image_hash)

Reklamaning tanlangan joylashuvda qanday ko'rinishini HTML (body ichida iframe) sifatida qaytaradi. Reklamani yoqishdan oldin odamga ko'rsatish uchun.

await ads.preview(
    token: str,
    ad_id: str,
    *,
    ad_format: str = 'MOBILE_FEED_STANDARD',
) -> list[dict]

• ▸ad_format standarti MOBILE_FEED_STANDARD; DESKTOP_FEED_STANDARD va boshqa formatlar Meta'ning ad preview hujjatida.
• ▸ads_read kerak.

Kerakli ruxsatlar:ads_read

previews = await ads.preview(user_token, ad_id, ad_format="INSTAGRAM_STANDARD")

Rasm baytlarini reklama kabinetining rasm kutubxonasiga yuklaydi va {"hash", "url", "raw"} qaytaradi. Kreativlar rasmga aynan shu hash orqali murojaat qiladi.

await ads.upload_image(
    token: str,
    *,
    ad_account_id: str,
    image: bytes,
    filename: str = 'ad.jpg',
) -> dict

• ▸image — yo'l emas, xom bytes; filename faqat yuklashdagi fayl nomi.
• ▸ads_management kerak.

Kerakli ruxsatlar:ads_management

with open("banner.jpg", "rb") as f:
    image = await ads.upload_image(user_token, ad_account_id="act_123", image=f.read(), filename="banner.jpg")

Mijozlar ro'yxati auditoriyasiga email va/yoki telefon bo'yicha odam qo'shadi. Qiymatlar serveringizda normallashtirilib SHA-256 bilan xeshlanadi — ochiq kontakt ma'lumoti serverdan chiqmaydi.

await ads.add_audience_users(
    token: str,
    audience_id: str,
    *,
    emails: Optional[list[str]] = None,
    phones: Optional[list[str]] = None,
    phone_country: Optional[str] = None,
    batch_size: int = 10000,
) -> dict

• ▸Normallashtirish: email bo'shliqlardan tozalanib kichik harfga o'tkaziladi; telefonda faqat raqamlar qoladi. Boshidagi nollar olib tashlanmaydi va davlat kodi qo'shilmaydi — raqamni xalqaro formatda bering, masalan +998901234567.
• ▸Meta bir so'rovda 10 000 tagacha yozuv qabul qiladi; katta ro'yxatni bir necha chaqiruvga bo'ling.
• ▸Ikkala ro'yxat berilsa ular qatorma-qator bitta odam deb birlashtiriladi: uzunligi va tartibi bir xil bo'lsin (ortiqcha elementlar tashlab yuboriladi).
• ▸ads_management kerak.

Kerakli ruxsatlar:ads_management

await ads.add_audience_users(user_token, audience_id, emails=["ali@example.com"], phones=["+998901234567"])

Bo'sh custom auditoriya yaratadi — standart holatda mijozlar ro'yxati (subtype="CUSTOM"), keyin u add_audience_users() bilan to'ldiriladi.

await ads.create_custom_audience(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    subtype: str = 'CUSTOM',
    description: Optional[str] = None,
    customer_file_source: str = 'USER_PROVIDED_ONLY',
    rule: Optional[dict] = None,
    **extra: Any,
) -> dict

• ▸Mijozlar ro'yxati uchun kabinet Meta'ning Custom Audience Terms shartlarini qabul qilgan bo'lishi kerak, aks holda Meta shartlar qabul qilinmagani haqida xato qaytaradi.
• ▸customer_file_source ma'lumot manbasini e'lon qiladi: USER_PROVIDED_ONLY (standart), PARTNER_PROVIDED_ONLY yoki BOTH_USER_AND_PARTNER_PROVIDED.
• ▸rule JSON qilib yuboriladi; boshqa Meta maydonlari **extra orqali. ads_management kerak.

Kerakli ruxsatlar:ads_management

audience = await ads.create_custom_audience(user_token, ad_account_id="act_123", name="Mijozlar")

Manba auditoriyadan bitta davlat uchun o'xshash (lookalike) auditoriya yaratadi. ratio qancha kichik bo'lsa, o'xshashlik shuncha yuqori va auditoriya shuncha kichik.

await ads.create_lookalike(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    origin_audience_id: str,
    country: str = 'UZ',
    ratio: float = 0.01,
) -> dict

• ▸ratio 0.01 dan 0.20 gacha (davlatdagi eng o'xshash 1–20%); standart 0.01, country standarti UZ.
• ▸Manba auditoriyada bitta davlatdan kamida 100 kishi bo'lishi kerak.
• ▸Lookalike to'lishi 1–6 soat oladi; shu vaqtda undan foydalanadigan ad set yaratish mumkin.
• ▸ads_management kerak.

Kerakli ruxsatlar:ads_management

lookalike = await ads.create_lookalike(user_token, ad_account_id="act_123", name="1% UZ", origin_audience_id="1202...", country="UZ", ratio=0.01)

Reklama kabinetidagi custom auditoriyalarni turi (subtype), taxminiy hajm chegaralari va yetkazish/ishlov holati bilan qaytaradi.

await ads.custom_audiences(
    token: str,
    *,
    ad_account_id: str,
    limit: int = 100,
) -> list[dict]

• ▸limit (standart 100) gacha bitta sahifa; ads_read kerak.

Kerakli ruxsatlar:ads_read

custom = await ads.custom_audiences(user_token, ad_account_id="act_123")
saved = await ads.saved_audiences(user_token, ad_account_id="act_123")

Ads Manager'da saqlangan auditoriyalarni (targeting shablonlari) targeting spetsifikatsiyasi va taxminiy hajmi bilan qaytaradi.

await ads.saved_audiences(
    token: str,
    *,
    ad_account_id: str,
    limit: int = 100,
) -> list[dict]

• ▸limit gacha bitta sahifa; ads_read kerak.

Kerakli ruxsatlar:ads_read

custom = await ads.custom_audiences(user_token, ad_account_id="act_123")
saved = await ads.saved_audiences(user_token, ad_account_id="act_123")

Kampaniya, ad set, reklama yoki kabinet bo'yicha sarf va natijalarni AdInsights (spend, impressions, reach, clicks, link_clicks, cpc, ctr, frequency) sifatida qaytaradi. Tezkor umumiy ko'rsatkichlar kartasi uchun.

await ads.insights(
    token: str,
    node_id: str,
    *,
    since: Optional[str] = None,
    until: Optional[str] = None,
) -> socialift.ads.AdInsights

• ▸since va until ikkalasini ham bering (YYYY-MM-DD); aks holda butun davr (date_preset=maximum) olinadi.
• ▸Faqat birinchi qator o'qiladi; kesimlar uchun insights_rows() ni ishlating.
• ▸ads_read kerak.

Tanlangan level dagi xom statistika qatorlarini ixtiyoriy breakdowns (age, gender, country, publisher_platform kabi) bilan qaytaradi. Qaysi segmentda natija arzonroq ekanini topish uchun.

await ads.insights_rows(
    token: str,
    node_id: str,
    *,
    level: str = 'campaign',
    date_preset: Optional[str] = 'last_30d',
    since: Optional[str] = None,
    until: Optional[str] = None,
    breakdowns: Optional[list[str]] = None,
    action_breakdowns: Optional[list[str]] = None,
    fields: Optional[str] = None,
    limit: int = 200,
) -> list[dict]

• ▸Meta kesimlarning faqat ba'zi kombinatsiyalarini qo'llab-quvvatlaydi: age + gender ishlaydi, age + country ishlamaydi.
• ▸since + until berilsa date_preset (standart last_30d) o'rniga ishlatiladi.
• ▸limit (standart 200) gacha bitta sahifa; ads_read kerak.

Kerakli ruxsatlar:ads_read

rows = await ads.insights_rows(user_token, "act_123", level="campaign", date_preset="last_7d", breakdowns=["age", "gender"])

Marketing API'ning istalgan yo'lini SDK imzolashi (access_token, appsecret_proof), qayta urinishlar va xato tasnifi bilan chaqiradi. O'rami yo'q endpoint'lar, masalan avtomatik qoidalar uchun.

await ads.call(token: str, path: str, *, method: str = 'GET', **params: Any) -> Any

• ▸Argumentlar tartibi token, path; method standarti GET. GET/DELETE dan boshqa hamma narsa POST bo'lib ketadi va haqiqiy obyektlarni o'zgartiradi.
• ▸dict/list qiymatlar avtomatik JSON qilinadi; mantiqiy qiymatlarni satr sifatida bering ("true"/"false").

Kerakli ruxsatlar:ads_read

data = await ads.call(user_token, "act_123/adcreatives", method="GET", fields="id,name")

Istalgan HTTP so'rovni yuboradi va JSON javobni qaytaradi — SDK'da hali alohida metodi yo'q endpoint uchun. Token va imzo parametrlarini (access_token, Meta uchun appsecret_proof — socialift.crypto.appsecret_proof) o'zingiz params yoki headers ga qo'shasiz.

await ads.request(
    method: str,
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    data: Optional[Any] = None,
    json: Optional[Any] = None,
    headers: Optional[Mapping[str, str]] = None,
) -> Any

• ▸params dagi None qiymatlar yuborilmaydi.
• ▸Limit (RateLimitError) va vaqtinchalik server xatolarida (HTTP 429, 500, 502, 503, 504) RetryPolicy bo'yicha qayta uriniladi; Retry-After sarlavhasi bo'lsa, shuncha kutiladi. Tarmoq uzilishi TransportError bo'lib chiqadi.

request("GET", ...) ning qisqa shakli.

await ads.get(url: str, **kw) -> Any

request("POST", ...) ning qisqa shakli.

await ads.post(url: str, **kw) -> Any

request("DELETE", ...) ning qisqa shakli.

await ads.delete(url: str, **kw) -> Any

Meta'ning kursorli sahifalashi (paging.next) bo'yicha yurib, barcha data elementlarini bitta ro'yxatga yig'ib qaytaradi.

await ads.paginate(
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    max_items: int = 500,
    page_size: int = 100,
) -> list[dict]

• ▸max_items (standart 500) — himoya chegarasi: yirik akkauntda ro'yxat o'n minglab yozuv bo'lishi mumkin. page_size — bitta so'rovdagi limit.

SDK o'zi yaratgan HTTP sessiyasini yopadi (tashqaridan berilgan sessiyaga tegmaydi). async with Client(...) ishlatilsa, o'zi chaqiriladi.

await ads.close() -> None