FACEBOOK وINSTAGRAM.
تستدعي كل عملية نقطة نهاية الإعلانات المقابلة في REST وتُرجع استجابتها دون تغيير. المصادقة والحدود مطابقة لـ REST. يُرجع الاستدعاء الفاشل خطأ GraphQL: يحمل extensions.status حالة REST، ويحمل extensions.code رمز خطأ Ayrshare عندما يتضمن خطأ REST رمزًا. راجع الأخطاء. تتطلب عمليات الإعلانات خطة Premium أو Business أو Enterprise. وبدون إحداها، يُرجع كل استدعاء خطأً بقيمة 403 في extensions.status وقيمة 169 في extensions.code.
العمليات
تأخذ كل عملية أيضًا وسيط
profileKey اختياريًا للعمل على User Profile (ملف المستخدم الشخصي). وتُرجع جميعها استجابة REST بصيغة JSON، لذا لا تقبل تحديد الحقول.
سرد الحسابات الإعلانية
ابدأ من هنا. استخدم قيمaccountId الواردة في الاستجابة حيثما تطلب عملية ما accountId.
البحث في خيارات الاستهداف
يحددkind نوع البحث: INTERESTS لاستهداف الجمهور، وREGIONS أو CITIES للمواقع. يأخذ كل نوع وسائطه الخاصة فقط. على سبيل المثال، لا يعمل countryCode وregionId إلا مع CITIES، ويتطلب INTERESTS الوسيط search.
سرد الإعلانات
مرّر واحدًا على الأقل منcampaignId أو accountId أو adId أو postId أو socialPostId. يمثّل socialPostId معرّف المنشور الخاص بالشبكة نفسها، للمنشورات التي لم تُنشر عبر Ayrshare.
معرفة تكلفة إعلان
إيقاف إعلان مؤقتًا أو استئنافه
يُغيّرupdateAd الإنفاق الإعلاني الفعلي. توقف PAUSED الإنفاق، وتستأنفه ACTIVE، وتُنهي DELETED أو ARCHIVED الإعلان. تُطبَّق الحالة نفسها أيضًا على مجموعة الإعلان والحملة التابعين للإعلان، لذا تتغير معها أي إعلانات أخرى في مجموعة الإعلان أو الحملة تلك. أما الحملة أو مجموعة الإعلان التي رُبط بها التعزيز باستخدام attachTo فتحتفظ بحالتها الخاصة، ولا يعمل الإعلان إلا عندما تكون الحملة ومجموعة الإعلان اللتان تعلوانه نشطتين.
تعزيز منشور
يُنفقboostPost أموالًا حقيقية من الحساب الإعلاني. فهو يحوّل منشورًا منشورًا بالفعل إلى إعلان.
- مرّر
postId(معرّف المنشور في Ayrshare) أوsocialPostId(معرّف المنشور الخاص بالشبكة نفسها). - احصل على
accountIdمنadAccounts. - تكون قيمة
budget.amountبعملة الحساب الإعلاني. لا تُغفلbudgetإلا عندما يضيفattachTo.adSetIdالإعلان إلى مجموعة إعلان تديرها بالفعل، إذ تحتفظ بميزانيتها الخاصة. وأغفلtargetingحينها أيضًا: إذ تحتفظ مجموعة الإعلان بإعداداتها الخاصة. راجع التعزيز ضمن حملة أو مجموعة إعلانات موجودة. - الوسائط
scheduleوtargetingوcallToActionوattachToوstatusاختيارية. إذا أغفلتstatusوschedule، يكون الإعلان نشطًا ويبدأ الآن وبلا تاريخ انتهاء، لذا يستمر في الإنفاق حتى توقفه مؤقتًا. اضبطstatus: PAUSEDأوschedule.endلتقييده. - ضع الإعدادات التي تنفرد بها منصة واحدة ضمن
platformOptions، مفهرسةً حسب المنصة. على Facebook وInstagram، يكونadNameوbidAmountمطلوبين هناك، على سبيل المثالplatformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }. وبدونهما، يُرجع التعزيز خطأ حقول مفقودة. ومعattachTo.adSetId، أغفلbidAmount: إذ تحتفظ مجموعة الإعلان بعرض السعر الخاص بها. - على Facebook وInstagram، ترفض Meta الإعلان حتى تكون للحساب الإعلاني طريقة دفع مرتبطة به، وحتى تكون الإعلانات المخصّصة مفعّلة للحساب المرتبط بالصفحة في الاتحاد الأوروبي والمنطقة الاقتصادية الأوروبية وسويسرا. راجع Boost Post.
JSON:
- يقبل
accountIdسلسلة نصية أو رقمًا. - تقبل تواريخ
scheduleتاريخًا أو تاريخًا ووقتًا بتنسيق ISO 8601، مثل"2026-10-10T09:00:00Z". استخدم هذه الصيغة بدلًا من رقم. ويقبلschedule.endأيضًا القيمة0لعدم تحديد تاريخ انتهاء. - تقبل مفاتيح المواقع قيمة واحدة أو قائمة.
- يقبل
targeting.interestsالمعرّفات كسلاسل نصية أو أرقام. - يقبل
platformOptionsكائنًا.
updateAd مع status: PAUSED. لا يزال boostFacebookPost وinstagramBoostPost يعملان.
لا تزال العمليات الخاصة بكل منصة، مثل facebookAdAccounts وinstagramAds، تعمل دون تغيير.