AD تقنيًا: كيف يعمل وكيف تدمجه

ما هو

ما هو AD ولمن هو

AD خادم إعلانات مباشر: لا مزاد ولا صندوق أسود. يبيع الناشر المساحة الإعلانية لموقع يديره أصلًا؛ ويختار المعلن المساحات بالضبط ويضبط الاستهداف ويطلق حملته. يمكن لحساب واحد أن يؤدي أيًّا من الدورين — أو كليهما.

الدخول

كيف تدخل

سجّل الدخول في forhosting.com واختر «إدارة AD الخاص بي» من قائمة حسابك. تُفتح اللوحة بـجلسة قصيرة — بيانات اعتماد تنتهي خلال دقائق (لا تتجاوز 60 دقيقة أبدًا) ولا تترك أي مفتاح دائم في المتصفح. عند انتهائها، افتحها مجددًا من القائمة نفسها.

للتكاملات، أنشئ مفتاح API من اللوحة (الملف الشخصي) أو عبر POST /tenants/:id/keys. نطاقان: tenant (وصول كامل إلى حسابك) وread (قراءة فقط، للوحات المتابعة والروبوتات). يُعرض المفتاح مرة واحدة؛ إن ضاع فأنشئ آخر وألغِ القديم.

يستطيع فريقنا فتح لوحتك «كعميل» لمساعدتك: تدوم تلك الجلسة 15 دقيقة على الأكثر وتحمل اسم من فتحها. لا تشغّل الشركة حسابك أبدًا بمفتاح دائم.

المعلنون

الحملات والاستهداف

الحملة هي الحاوية: الاسم والتواريخ والميزانيات الاختيارية والاستهداف الذي تتشاركه تصاميمها. تولد بحالة draft؛ وأنت من يجعلها active أو يوقفها مؤقتًا أو ينهيها. لا تُعرض إلا التصاميم النشطة لحملة نشطة — وإيقاف الحملة مؤقتًا يوقف العرض فورًا.

من بين التصاميم المؤهلة يختار المحرك عشوائيًا، موزونًا بالوزن الذي تمنحه لكل تصميم. التصميم الذي له حد تسليم يخضع لـضبط الوتيرة: كل 5 دقائق يُعاد ضبط وزنه كي تتوزع الميزانية على أيام الحملة بدل أن تحترق صباحًا. ضبط الوتيرة يبطئ فقط — ولا يختلق حركة أبدًا.

لا يُعرض التصميم إلا في مساحة له فيها طلب مدفوع (انظر «شراء المساحات»). الحملة والتصميم والمساحة والطلب كلها مرئية في اللوحة (الحملات، التصاميم، شراء المساحات).

المعلنون

التصاميم: ستة أنواع ووسم واحد

لكل تصميم رابط نقر وحجم ثابت اختياري ووزن. الحدود في هذا الجدول هي التي تفرضها واجهة API عند الرفع — تُقرأ من الشيفرة ولا تُكتب هنا.

عقد HTML5

يُحمَّل index.html الخاص بك داخل iframe مع وجهة النقر في سلسلة الاستعلام باسم clickTag. اقرأه واستخدمه كـhref لمنطقتك القابلة للنقر — ذلك الرابط موقَّع ويحتسب النقرة؛ أما الرابط المكتوب يدويًا فلا يُحتسب.

// index.html — the click goes where the engine says
var clickTag = new URLSearchParams(location.search).get("clickTag");
document.getElementById("ad").href = clickTag;

إذا احتاج تصميمك إلى أن يكبر، فأخبر الصفحة بارتفاعه الحقيقي عبر postMessage. يخبر الوسم التصميم أيضًا بعرض الحيّز عند التحميل وعند كل تغيير للحجم، ويرسل visible أول مرة يدخل فيها الحيّز نطاق الرؤية — وهي اللحظة المناسبة لبدء حركة. تُطبَّق الارتفاعات حتى 10000 بكسل.

// creative → page: ask for the real height (applied up to 10000 px)
parent.postMessage({ fh: "resize", nh: document.documentElement.scrollHeight }, "*");

// page → creative: { fh: "size" | "visible" }
window.addEventListener("message", function (ev) {
  if (ev.data && ev.data.fh === "visible") { /* start your animation */ }
});

تصميم بسيط يفعل الأمرين معًا، جاهز للرفع كما هو: نزّل ملف ZIP النموذجي

ماكروهات تصاميم السكربت

في تصميم script يستبدل المحرك هذه العناصر النائبة عند نشر المساحة. قالب اللوحة هو الشيء نفسه مع عناصر نائبة إضافية تملؤها في نموذج.

تتبّع الأطراف الثالثة والموافقة

يمكن لأي تصميم أن يحمل شيفرة تتبّع (بكسل أو سكربت من مزوّد قياس). تُخرَج بعد الإعلان مع تحويل كل src إلى data-src، فلا يُحمَّل شيء حتى يسمح الوسم بذلك.

إذا حددت معرّف المزوّد في IAB TCF v2، فلا تُحمَّل الشيفرة إلا بعد موافقة الزائر على ذلك المزوّد، مع تعبئة ${GDPR} و${GDPR_CONSENT_n}. ينتظر الوسم مدير الموافقة في الموقع حتى 10 ثوانٍ؛ ومن دون معرّف مزوّد تُحمَّل الشيفرة كعنصر عادي.

المراجعة اليدوية

يولد كل تصميم بحالة en_revision ويراجعه شخص قبل أن يُعرض. بعد الموافقة تجعله active أو paused؛ وعند الرفض ترى السبب ويمكنك التعديل وإعادة الإرسال. لا يصل إلى الزائر أي شيء من تصميم غير مُراجَع — لا الترميز ولا السكربت ولا شيفرة التتبّع.

تغيير رابط النقر أو المحتوى أو الملف في تصميم موافَق عليه يعيده إلى المراجعة: ما وُوفق عليه هو ما يُعرض، ولا شيء غيره أبدًا.

المعلنون

شراء المساحات

يعرض المعرض كل مساحة معروضة للبيع: الموقع والحجم والصيغ المقبولة ونموذج البيع والسعر الذي حدده الناشر. تختار مساحة، وتصميمًا بصيغة تقبلها المساحة، وميزانية، وتاريخ بداية. يستخدم التسعير والخصم المعادلة نفسها:

الحد الأدنى للطلب $5؛ ويرفض التسعير أي مبلغ أقل. الطلب شراء مسبق الدفع لحجم معين — يتحرك المال مرة واحدة عند الشراء. أرسل idempotencyKey فيعيد الطلب المتكرر الطلب نفسه بدل إنشاء طلب ثانٍ.

كيف تدفع

عند تعليم الطلب مدفوعًا، يُقيَّد 80% من سعره النهائي لناشر المساحة — على الطلب كاملًا لا بالتناسب مع التسليم. تُعاد المساحة للنشر فورًا ويبدأ عرض تصميمك في الدقيقة التالية.

الناشرون

المواقع والمساحات والوسم والمدفوعات

المواقع

سجّل موقعًا بنطاقه (كن ناشرًا). يولد معلقًا ويتحقق منه شخص قبل أن تستطيع مساحاته البيع — فالنطاق غير المُتحقق منه لا يستطيع كسب حصة. سحب موقع يبدأ فترة تهدئة مدتها 90 يومًا على النطاق: لا يستطيع أحد آخر تسجيله في أثنائها ووراثة سجله.

المساحات

المساحة هي الحيّز القابل للبيع: اسم، وحجم بالبكسل (أو -1 لعرض متكيّف)، والصيغ التي تقبلها، ونموذج بيع بسعره، وما إذا كانت معروضة في المعرض. يمكنك تعيين تصميم احتياطي خاص بك يُعرض حين لا يكون هناك مؤهل آخر — وهو يتجاوز الاستهداف والحدود.

يعمل سلوكان اختياريان في متصفح الزائر: التحديث التلقائي (طلب جديد كل N ثانية، بحد أدنى 5؛ التبويب المخفي لا يُحدَّث أبدًا، والحيّز الذي يعود فارغًا يحتفظ بالإعلان السابق) وتمرير المعاملات (تسافر سلسلة استعلام الصفحة مع النقرة إلى وجهة المعلن). تعلن المساحة البينية أيضًا أي الروابط تشغّل الطبقة — افتراضيًا p a, nav a, h2 a — والثواني قبل إمكان إغلاقها.

الوسم

الصقه حيث يجب أن يظهر الإعلان. معرّف المساحة من اللوحة (المواقع والمساحات). الوسم نفسه يعرض كل الصيغ التي تقبلها المساحة؛ والمساحة البينية تستخدم الوسم القياسي أيضًا.

القياسي (div وscript، غير متزامن):

<div data-fh-ad="zon_XXXXXXXXXXXXXXXXXXXXXXXX"></div>
<script src="https://api.ad.forhosting.com/ad-tag.js" async></script>

القديم، لأنظمة إدارة المحتوى التي لا تشغّل سكربتات غير متزامنة:

<script src="https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=js"></script>

رابط نصي: عنوان URL يحتسب الظهور ويعيد التوجيه إلى المعلن:

https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=link

الوسم يُحدِّث نفسه: لا يحمل رابطه رقم إصدار ولا يتغيّر أبدًا، لذا يصل أي تحسين من جانبنا إلى كل المواقع خلال نحو undefined دقيقة دون أن يعدّل أحد أي قالب (يقدّم اليوم v6، في ترويسة x-tag-version). ينتظر حتى تنتهي صفحتك من التحميل قبل أن يطلب أي شيء، فلا تزاحم الإعلانات محتواك أبدًا. علاماته الوحيدة في صفحتك هي الخاصية data-fh-ad ومعرّف الطبقة — جرى فحصها مقابل قوائم حجب الإعلانات الشائعة دون أي تطابق. وتستخدم حدود التكرار كوكي من الطرف الأول.

المدفوعات

تتراكم حصتك البالغة 80% من كل طلب مدفوع في اللوحة (المدفوعات). عندما يبلغ المتراكم $10، اطلب الدفع بالطريقة المحددة في ملفك (paypal, bank, other)؛ يدفع فريقنا خارج اللوحة ويسجّل المرجع.

الحالات: accrued ← requested ← processing ← paid؛ ويعود إليك الدفع الفاشل مع السبب كي تطلبه مجددًا ببيانات مصحَّحة.

للجميع

التقارير

يُحتسب الظهور والنقرات وبداية/نهاية الفيديو عند الحافة، مع كل طلب. قبل الاحتساب تُرشَّح الحركة: الزواحف المعروفة بوكيل المستخدم، وشبكات مراكز البيانات، والطلبات ذات درجة روبوت منخفضة جدًا، وأي IP يكرر الطلب نفسه خلال 2 ثانية. الطلب المُرشَّح يحصل مع ذلك على إعلانه أو إعادة توجيهه — ما يُحمى هو العدّاد فقط.

كل 5 دقائق تُجمَّع الأعداد في صفوف يومية لكل تصميم ومساحة ومضيف مُحيل. قد يتأخر اليوم الجاري بهذا المقدار؛ أما الأيام المُقفلة فلا تتغير أبدًا.

تعرض اللوحة (التقارير) الإجماليات وسلسلة يومية، وCTR (النقرات ÷ الظهور × 100) وeCPM (القيمة المُسلَّمة × 1000 ÷ الظهور)، لجهة المعلن أو جهة الناشر، وقائمة بالأعلى حسب التصميم أو المساحة أو الحملة أو الموقع أو مضيف المُحيل. يُحفظ مضيف المُحيل فقط، لا عنوان URL أبدًا.

الدمج

مرجع واجهة API

العنوان الأساسي https://api.ad.forhosting.com. أرسل مفتاحك كرمز Bearer؛ والأجسام والردود بصيغة JSON. لكل رد الشكل {"success":true,"data":…} أو {"success":false,"error":{"code","message"}} مع حالة HTTP المطابقة.

curl https://api.ad.forhosting.com/me \
  -H "Authorization: Bearer ads_ten_…"

نطاقات بيانات الاعتماد

بيانات اعتماد tenant أو read أو session تعمل دائمًا على حسابها — ويُتجاهل أي tenantId يرسله العميل. المعرّف الذي يخص شخصًا آخر يعيد 404 لا 403: لا تؤكد واجهة API وجوده أبدًا.

المسارات

كل مسار تعلنه الخدمة، مع النطاق الذي يطلبه الموجّه — مشتق من الموجّه نفسه في كل بناء.

عام: بلا بيانات اعتماد — مسار العرض · أي: أي بيانات اعتماد صالحة، على حسابها · قراءة: tenant أو session أو read · كتابة: tenant أو session (يُرفض read) · system: الشركة فقط

أخطاء يجدر معرفتها: 401 unauthorized (بيانات اعتماد مفقودة أو منتهية)، 403 forbidden (النطاق لا يستطيع ذلك)، 404 not_found، 400 bad_request مع السبب في الرسالة، 409 conflict (انتقال حالة غير مسموح)، 402 insufficient_balance عند دفع طلب، و503 payments_disabled إذا كانت المبيعات متوقفة.

الأسئلة الشائعة

أسئلة تقنية