الانتقال إلى المحتوى الرئيسي
تأخذ عمليات الإعلانات منصة الإعلانات كوسيط، لذا تعمل العملية نفسها على كل منصة إعلانات يدعمها Ayrshare. وهي حاليًا 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 كائنًا.
أرسل idempotencyKey جديدًا، مثل UUID، مع كل عملية تعزيز. إذا انتهت مهلة استدعاء أو فشل، فأعد المحاولة بالمفتاح نفسه والوسائط نفسها.
  • إذا اكتمل التعزيز الأول، تُرجع إعادة المحاولة استجابته بدلًا من إنشاء إعلان ثانٍ والدفع مقابله.
  • إذا كان التعزيز الأول لا يزال قيد التنفيذ، تُرجع إعادة المحاولة خطأً بقيمة 409 في extensions.status. انتظر، ثم أعد المحاولة بالمفتاح نفسه. لا تنتقل إلى مفتاح جديد.
  • تُرجع إعادة استخدام مفتاح مع وسائط مختلفة أيضًا 409.
لإيقاف إنفاق الإعلان، استدعِ updateAd مع status: PAUSED. لا يزال boostFacebookPost وinstagramBoostPost يعملان. لا تزال العمليات الخاصة بكل منصة، مثل facebookAdAccounts وinstagramAds، تعمل دون تغيير.