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

ما هو

ما هو AD ولمن هو

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

الدخول

كيف تدخل

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

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

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

المعلنون

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

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

بين الحملات المؤهلة لا يختار المحرك عشوائيًا: بل يتناوب. يعرض واحدة ثم الأخرى، ولا يفصل الوزنُ الذي تمنحه لكل تصميم إلا عند التعادل — فعرض الحملة نفسها على الزائر نفسه عشر مرات متتالية لا يبيع شيئًا. تُحسب النوبات لكل زائر ولكل مساحة، في متصفح الزائر نفسه؛ ومع حجب الكوكيز يتراجع إلى الاختيار العشوائي الموزون. والتصميم الذي له حد تسليم يخضع كذلك لـضبط الوتيرة: كل 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 يستبدل المحرك هذه العناصر النائبة عند نشر المساحة. قالب اللوحة هو الشيء نفسه مع عناصر نائبة إضافية تملؤها في نموذج.

عدة وجهات في تصميم واحد

يمكن للتصميم أن يحمل حتى 8 وجهة مسمّاة إضافة إلى رابط النقر الرئيسي — زر App Store وزر Google Play في القطعة نفسها مثلًا. لكل واحدة معرّف لا يتجاوز 20 حرفًا صغيرًا؛ وmain محجوز للرابط الرئيسي.

في تصميم HTML5 تصل في سلسلة الاستعلام باسم clickTag_<id> إلى جانب clickTag المعتاد؛ وفي تصميم script تكتب [CLICKTAG:<id>]. تمر كل واحدة منها بمتتبّع النقر، فتُضاف إلى الإجمالي وتُفصَّل لكل زرّ في التقارير.

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

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

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

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

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

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

المعلنون

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

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

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

كيف تدفع

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

الناشرون

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

المواقع

سجّل موقعًا بنطاقه (كن ناشرًا). يولد معلقًا ثم يتحقق من نفسه: انشر الرمز الذي نعطيك إياه على /.well-known/fh-ad-site-verification.txt أو في الصفحة الرئيسية، واطلب التحقق، فيُفعَّل الموقع من تلقاء نفسه — بلا طابور وبلا أن يضطر أحد هنا للنظر فيه أولًا. والنطاق غير المُتحقق منه لا يستطيع كسب حصة. سحب موقع يبدأ فترة تهدئة مدتها 90 يومًا على النطاق: لا يستطيع أحد غيرك تسجيله في تلك المدة ووراثة سجلّه.

المساحات

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

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

كيف يُشغَّل الإعلان البيني

الطبقة العائمة خاصية للمساحة لا للموقع: لا شيء يُلصق من أجلها — الوسم يبني ما يحتاجه — وأنت تغيّر الوتيرة من اللوحة التي تشتري منها. أربعة أنماط:

الوتيرة الثابتة تُتعب الزائر في اليوم الثلاثين كما في اليوم الأول — ولهذا وُجد الجدول المتدرّج: يجبي الظهور الأول مبكرًا ثم يتنحّى. يعيش العدّ في متصفح الزائر نفسه؛ وإذا كان التخزين محجوبًا فيتراجع إلى العدّ في الذاكرة بدل أن ينكسر.

متى تُطلب الإعلانات — موقعك أولًا

يجب ألا تبطئ الإعلانات موقعك، والإعداد يعيش هنا لا في ترميزك. يختار كل موقع متى يطلب الوسم أول إعلان له:

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

الوسم

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

القياسي (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

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

إذا تكرر الموضع نفسه على امتداد الصفحة — «كل N مشاركة» في منتدى مثلًا — فإن الوسم يطلب كل نسخه في طلب واحد (حتى 10)، ويتقدّم حد التكرار داخل تلك الدفعة، فلا يستطيع تصميم واحد أن يملأ كل حيّز في الصفحة. وإن لم يفهم جانبنا الدفعة، فالوسم يتراجع إلى حيّز واحد في كل مرة بدل أن يترك الصفحة فارغة. وتكرار المساحة أمر يُعلَن لدينا: القاعدة مساحة واحدة لكل موضع، لأن المساحة هي ما يجمع التقرير حسبه.

أين يظهر الإعلان — دون المساس بقالبك

تستطيع المساحة أن تعلن أين مكانها: محدِّد CSS (حتى 300 حرفًا) وموضع بالنسبة لما يجده ذلك المحدِّد. الوسم هو الذي ينشئ المساحة، فنقل إعلان يكلّف تغييرًا في اللوحة لا تعديلًا في قالبك.

رقمان اختياريان يحكمان التكرار: أحدهما يضع المساحة كل N تطابق (حتى 50)، وسقف يحدّ عدد المساحات المُنشأة — 4 افتراضيًا عند التكرار، و20 حدًّا أقصى. هناك سقف دائمًا: محدِّد فضفاض مثل p يطابق مئات المرات في مقال طويل، وهذا الحد لا يصح أن يتوقف على تذكُّر من يضبط الإعداد.

أمران يستحقان المعرفة. عنصر data-fh-ad تضعه أنت في القالب هو المُقدَّم: لن يضيف الوسم مساحة ثانية لتلك المساحة، فتستطيع الانتقال من طريقة إلى أخرى دون أن تدفع ظهورين مقابل واحد. والمحدِّد الذي لا يطابق شيئًا لا يُصدر خطأ — صفحتك تبدو سليمة تمامًا بلا الإعلان واللوحة تبقى خضراء. تحقق من الموضع في متصفح، على سطح المكتب وعلى عرض الهاتف: قد يوجد محدِّد في المقال ولا يوجد في الصفحة الرئيسية، أو يقيس 1360 بكسل على سطح المكتب و0 على الهاتف.

ووردبريس: لا شيء تلصقه

إن كان موقعك يعمل بووردبريس فهناك إضافة، forhosting-ad. تُثبّتها فتُعرّف بنفسها: تنشر تحديًا على نطاقك أنت، ونقرؤه نحن، ويُسلَّم الاعتماد مرة واحدة فقط. لا تكتب مفتاحًا ولا معرِّفًا ولا رمزًا — وإثباتك أنك تتحكم بالنطاق ليس كأن تكون مدعوًّا: لا يصدر شيء حتى تتم الموافقة على الموقع.

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

وهناك إضافة ثانية، forhosting-ad-updater، تستقبل حزمة وتثبّتها. هذه بحكم تصميمها قناة تنفيذ عن بُعد، لذلك لا نثبّتها إلا على مواقعنا نحن؛ أما لديك فتصل التحديثات عبر قناة ووردبريس نفسها وأنت تقرر متى تطبّقها.

المدفوعات

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

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

للجميع

التقارير

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

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

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

يمكن أيضًا ترشيح أي من هذه العروض حسب الحملة أو التصميم أو المساحة أو مضيف المُحيل أو الوجهة، والأرقام نفسها متاحة عبر واجهة API.

قبل احتساب أي شيء تمر الحركة بمرشّح الروبوتات، وتشغّله الشركة بأحد ثلاثة أنماط: block (الافتراضي: الطلبات المُرشَّحة تحصل مع ذلك على إعلانها، لكنها لا تُحتسب)، وlog (تُحتسب وتُسجَّل على حدة، للقياس قبل القرار)، وoff.

الدمج

مرجع واجهة 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 إذا كانت المبيعات متوقفة.

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

أسئلة تقنية