QiAds Web SDKدليل المطوّرين

qiads.js سكربت واحد بلا اعتماديات يعرض الإعلانات الحيّة الآن على موضع من مواضع QiAds — بنراً متبدّلاً أو بطاقة داخل المحتوى أو نافذة منبثقة — في أي صفحة ويب أو داخل WebView في تطبيق، ويقيسها. يُقدَّم من الأصل نفسه الذي يقدّم الواجهة البرمجية للإعلانات: https://qi-ads.com.

ما الذي يقيسه (أعداد مجمّعة لكل يوم بتوقيت بغداد؛ التعريفات الكاملة في منهجية القياس):

ما لا يفعله أبداً: لا يضع ملفات تعريف ارتباط ولا يقرؤها (استثناء واحد: حدّ تكرار النافذة المنبثقة في صفحة بلا تخزين محلي، انظر الخصوصية)، ولا معرّفات دائمة، ولا بصمة للجهاز، ولا أسماء أو أرقام هواتف أو حسابات، ولا يرسل الجزء بعد ? من عنوان الصفحة.

يُرسم كل إعلان داخل Shadow DOM (عنصر <qiads-slot> داخل الخانة، و<qiads-popup> للنافذة)، فلا تصل إليه أنماط صفحتك ولا يغيّر هو شيئاً فيها. في المحرّكات التي لا تدعم Shadow DOM يُرسم الإعلان مباشرة بأنماط محصورة في أصناف .qiads*.

دائم التحديث (موصى به)

<script async src="https://qi-ads.com/qiads.js" data-site="superqi"></script>

/qiads.js هو دائماً أحدث إصدار من 1.x. يُحفظ في الكاش 5 دقائق مع إعادة تحقق في الخلفية حتى يوم، فيصل كل إصلاح إلى كل صفحة خلال دقائق دون أن تغيّر شيئاً في كودك. لا يكسر أي إصدار من 1.x ما يعمل اليوم (انظر سياسة الإصدارات).

مثبّت الإصدار مع Subresource Integrity

<script async src="https://qi-ads.com/sdk/1.3.1/qiads.js"
        integrity="sha384-…" crossorigin="anonymous" data-site="superqi"></script>

/sdk/<الإصدار>/qiads.js لا يتغيّر أبداً (كاش سنة كاملة، immutable)، فيمكن تثبيته ببصمة SRI: يرفض المتصفح الملف إن تغيّر بايت واحد. قيمة integrity الدقيقة تُطبع في صفحة دليل المطوّرين وفي «كود التضمين» في لوحة الإدارة، من ملف الإصدار نفسه. الترقية قرار منك: غيّر الإصدار والبصمة معاً. crossorigin="anonymous" شرط لعمل SRI، والخادم يرسل Access-Control-Allow-Origin: * لهذه الملفات. النسخة السابقة باقية للرجوع إليها: /sdk/1.2.1/qiads.js.

التحميل

يعمل الوسم كما هو داخل Android WebView وiOS WKWebView، لكن على التطبيق المضيف ثلاثة أمور: أين تُفتح النقرة، ومتى تكون الشاشة ظاهرة فعلاً، وأي أصول يثق بها.

إعدادات WebView

النقرات: سلّمها إلى التطبيق

لا تضع data-target="_self" داخل تطبيق أبداً: ستُفتح صفحة المعلن داخل WebView التطبيق نفسه، بجوار أي جسر برمجي (JS bridge) يكشفه التطبيق. ولا يكفي الافتراضي _blank: في Android (والإعداد الافتراضي setSupportMultipleWindows(false)) يتحوّل إلى انتقال يستبدل شاشتك، وفي WKWebView لا يحدث شيء ما لم يُنفَّذ createWebViewWith. الطريقة الصحيحة أن تستلم النقرة:

document.addEventListener("qiads:click", function (event) {
  var bridge = window.SuperQiBridge                     // كائن الجسر في تطبيقك
  if (!bridge || !bridge.openExternal || !event.detail.url) return   // بلا جسر: يُفتح الرابط كالمعتاد
  event.preventDefault()                                // لا ينتقل السكربت بنفسه
  bridge.openExternal(event.detail.url)                 // يفتحه التطبيق في Custom Tabs أو SFSafariViewController
})

ألغِ النقرة فقط حين يوجد الجسر ورابط تسلّمه إليه: إلغاؤها ثم فشل استدعاء الجسر (صفحة فُتحت في متصفح عادي، أو نسخة أقدم من التطبيق) يضيّع النقرة، فلا انتقال ولا احتساب. أو عبر الإعداد: QiAds.init({ onClick: function (detail) { if (window.SuperQiBridge && detail.url) { SuperQiBridge.openExternal(detail.url); return false } } }).

detail.url هو رابط التحويل من QiAds (https://qi-ads.com/api/ads/click/…). افتحه في متصفح داخل التطبيق: Custom Tabs في Android وSFSafariViewController في iOS، فتُحتسب النقرة حين يتبع المتصفح التحويل إلى صفحة المعلن. لا تحلّ الرابط أولاً بعميل HTTP (OkHttp أو URLSession): تلك ليست نقرة المستخدم، وتُصنَّف روبوتاً، ويخسر المستخدم صفحة الوجهة.

إن لم تمرّ النقرة عبر الجسر، فاعترض الانتقال في الطبقة الأصلية:

webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
        val url = request.url
        if (url.host == "your-own-host.example") return false   // صفحاتك تبقى في WebView
        CustomTabsIntent.Builder().build().launchUrl(view.context, url)
        return true
    }
}

// WKUIDelegate: روابط _blank
func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration,
             for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
    if let url = navigationAction.request.url { present(SFSafariViewController(url: url), animated: true) }
    return nil
}

// WKNavigationDelegate: كل نقرة على رابط خارجي
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction,
             decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
    if navigationAction.navigationType == .linkActivated,
       let url = navigationAction.request.url, url.host != "your-own-host.example" {
        present(SFSafariViewController(url: url), animated: true)
        decisionHandler(.cancel)
        return
    }
    decisionHandler(.allow)
}

قيّد الجسر البرمجي بأصولك أنت: WebViewCompat.addWebMessageListener مع allowedOriginRules في Android، والتحقق من message.frameInfo.securityOrigin في iOS. معاينة الرابط بالضغط المطوّل في iOS تفتح الرابط دون حدث نقر — ومع ذلك تُحتسب النقرة لأن التحويل يمرّ بخادم QiAds.

دورة الحياة: الظهور والتحديث

WebView بارتفاع محتواه (قيد معروف)

إن وُضع WebView بكامل ارتفاع محتواه داخل ScrollView أصلي، فلا تعرف الصفحة ما الظاهر على الشاشة: يرى IntersectionObserver كل خانة ظاهرة، فتُضخَّم المشاهدات الفعلية. اجعل WebView بحجم الشاشة يمرّر محتواه بنفسه، أو أخبرنا — واجهة يمرّر بها التطبيق موضع التمرير مدرجة في خارطة الطريق.

قوائم السماح وCSP

اسمح بـ https://qi-ads.com لـ: السكربت، والاتصال (serve وtrack)، والصور (الإبداعات)، والانتقال (رابط التحويل /api/ads/click/… الذي يرسل المستخدم بعده إلى نطاق المعلن). قوائم النطاقات في البرامج المصغّرة تحتاج الأصل نفسه. مثال CSP: script-src https://qi-ads.com; connect-src https://qi-ads.com; img-src https://qi-ads.com.

قائمة الفحص على أجهزة حقيقية

للشاشات الأصلية التي لا WebView فيها استعمل الواجهة البرمجية REST:

خصائص وسم السكربت

الخصائص المنطقية (data-test وdata-debug وdata-observe) تعمل بمجرد وجودها؛ القيم 0 وfalse وno وoff تطفئها.

خصائص الخانة

الاسم البديل data-qiads-* يُقرأ قبل الاسم القصير، وهو مفيد حين يتعارض اسم قصير مع إطار عمل يستعمل data-format مثلاً. لا يوجد بديل لـ data-lang.

خصائص يكتبها السكربت (مخرجات)

لا تضبطها بنفسك ولا تقرأها كمدخل: لهذا السبب لا يوجد الاسم البديل data-qiads-lang لـ data-lang — لو وُجد لقرأ السكربت لغته المعروضة (العربية الاحتياطية) عند التحديث وثبّتها.

window.qiadsConfig وQiAds.init(options)

الأولوية: window.qiadsConfig (يُقرأ عند التحميل) ← خصائص الوسم data-* تتقدّم عليه ← QiAds.init(options) يتقدّم على الاثنين من لحظة استدعائه. ويفعّل ?qiads_test=1 و?qiads_debug=1 في عنوان الصفحة الوضعين أيضاً.

QiAds.version                          // "1.3.1"
QiAds.config                           // الإعداد الحالي (للقراءة)
QiAds.init(options?)                   // يقرأ الإعداد ويملأ كل [data-qiads] جديد
QiAds.render(target, options?)         // Promise<boolean> — target: عنصر أو محدِّد CSS
QiAds.popup(placement, options?)       // Promise<boolean>
QiAds.close()                          // يغلق النافذة المفتوحة
QiAds.destroy(target?)                 // خانة واحدة، أو بلا وسيط: كل الخانات والنافذة
QiAds.on(type, fn)                     // يستمع لحدث (انظر الأحداث)
QiAds.off(type, fn)                    // يلغي الاستماع
QiAds.refresh(target?)                 // Promise<boolean> — ظهور جديد: معرّفات جديدة وإعلانات محدّثة
QiAds.setVisible(visible)              // ظهور التطبيق المضيف: false يوقف القياس والتبديل
QiAds.getSlots()                       // الخانات في الصفحة: {el, placement, format, state, lang, creatives}
QiAds.getVersion()                     // "1.3.1"

خيارات render: placement وformat وlimit وrotate وtarget وfallback وlang وdir وcap وaspect وcollapse وpage — كل خيار يتقدّم على خاصية الخانة المقابلة.

طابور الأوامر يعمل قبل تحميل السكربت، ويُنفَّذ بعد اكتمال تحليل الصفحة:

window.qiads = window.qiads || []
qiads.push(["render", "#slot", { placement: "superqi_homepage_slot" }])
qiads.push(["setVisible", false])
qiads.push(function (api) { api.on("impression", function (d) { console.log(d.creative.id) }) })

// أو بأسلوب GPT:
window.QiAds = window.QiAds || { cmd: [] }
QiAds.cmd.push(function () { QiAds.refresh() })

كل أمر باسم دالته ثم وسائطها؛ والدالة في الطابور تُستدعى مع الواجهة. بعد التحميل يصبح window.qiads وQiAds.cmd كائنين لهما push ينفّذ الأمر فوراً. كل دالة تلتقط أخطاءها: خطأ في السكربت لا يصل إلى صفحتك.

كل حدث يصل بطريقتين بالتفاصيل نفسها: QiAds.on(type, fn)، وحدث DOM باسم qiads:<type> يصعد (bubbles) من عنصر الخانة (ومن document لنافذة فُتحت بلا خانة).

الترتيب لإبداع واحد: request ← render ← impression، ثم click وclose حين تحدث؛ وempty أو error بدل render حين لا تُملأ الخانة.

التفاصيل (event.detail أو وسيط الدالة):

إلغاء النقرة يتم بأي من: event.preventDefault() على حدث DOM، أو detail.preventDefault()، أو إعادة false من مستمع on("click") أو من onClick. عندها لا ينتقل السكربت، ويفتح التطبيق detail.url بنفسه فتبقى النقرة محتسبة. النقرة التي لا يعلّمها المتصفح نقرة حقيقية (isTrusted = false، مثل el.click() من سكربت) لا تنتقل ولا تطلق أحداثاً.

QiAds.on("empty", function (d) { document.querySelector("#promo").hidden = true })
QiAds.on("impression", function (d) { analytics.track("ad_viewable", { placement: d.placement }) })

حجز المساحة (منع القفز): احجز صندوق الخانة قبل وصول الإعلان بنسبة الموضع. أبسط طريقة سمة style="aspect-ratio:9/4" على الخانة؛ وإن منعت سياسة CSP في صفحتك سمات style فضعها في ملف الأنماط: [data-qiads="superqi_homepage_slot"]{aspect-ratio:9/4}. وأضف data-aspect="9/4" ليحجز السكربت المساحة بنفسه في المحرّكات التي لا تدعم aspect-ratio (بديل padding-top). بعد ردّ الخادم يأخذ الصندوق نسبة الموضع الفعلية.

الطيّ: بلا إعلان تُخفى الخانة (display:none) افتراضياً. data-fallback يُبقي محتواها الأصلي (إعلان داخلي مثلاً)، وdata-collapse="never" يُبقي الصندوق المحجوز بخلفية محايدة فلا يتحرك المحتوى تحته.

لكل إبداع نسخة عربية دائماً، وقد يرفع المعلن معها نسخة إنجليزية أو كردية. رابط الإعلان واحد لكل اللغات. لغة الخانة أول قيمة معروفة من: lang في QiAds.render ثم data-lang على الخانة؛ ثم data-lang على الوسم؛ ثم <html lang> (en* ← en · ku وckb* وkmr* ← ku · ar* ← ar)؛ وإلا ar. القيمة غير المعروفة تُتجاهل.

قاعدة الرجوع: تُعرض نسخة اللغة المطلوبة إن رُفعت لها صورة، وإلا النسخة العربية للحملة نفسها؛ لا تختفي حملة لأنها بلا ترجمة، ولا تُخلط لغتان في إعلان واحد. data-qiads-lang على الخانة وcreatives[].lang في ردّ serve يبيّنان اللغة المعروضة فعلاً. الاتجاه يتبع لغة ما يُعرض (rtl للعربية والكردية) ما لم تُضبط data-dir، وشارة «إعلان» تتبعها (إعلان · Ad · ڕیکلام). تُحتسب الأرقام للإبداع أياً كانت اللغة.

المصطلحات من إرشادات MRC وIAB، وهي النصوص نفسها التي تعرضها التقارير ولوحة الإدارة:

تفاصيل القياس:

لا نجمع: عنوان IP نفسه، ولا ملفات تعريف ارتباط (الخادم لا يضع شيئاً ولا يقرأ شيئاً)، ولا أسماء أو هواتف أو حسابات، ولا معرّفات إعلانية، ولا الجزء بعد ? أو #، ولا الصفحة المُحيلة كاملة، ولا الموقع الجغرافي. حين يحذف الملح اليومي بعد يومين لا يمكن ربط رموز ذلك اليوم بعنوان. يحفظ السكربت في المتصفح وقت آخر نافذة منبثقة فقط، في localStorage أو sessionStorage، وإن كان التخزين معطّلاً ففي كوكي بالاسم نفسه على نطاق صفحتك. قد تحفظ سجلات تشغيل Cloudflare بيانات الطلب (العنوان وهوية المتصفح) حتى 7 أيام. التفاصيل في سياسة الخصوصية.

وضع الاختبار — data-test على الوسم، أو ?qiads_test=1 في عنوان الصفحة، أو QiAds.init({ test: true }): يعرض كل شيء ويطلق كل الأحداث، لكن الإرسال يحمل test:1 ورابط النقر يحمل t=1، فيُحوَّل المستخدم ولا يُحتسب شيء. صفحة المعاينة /ads-demo.html في وضع الاختبار دائماً.

وضع التشخيص — data-debug، أو ?qiads_debug=1، أو QiAds.init({ debug: true }): يكتب كل خطوة بـ console.info (يظهر في chrome://inspect وSafari Web Inspector)، ويحيط كل إعلان بإطار، ويرسل بـ fetch مع keepalive ليقرأ حكم الخادم من الترويسة X-QiAds-Result ويطبعه:

الترويسة مكشوفة للقراءة من أي أصل (Access-Control-Expose-Headers)، وتحملها أيضاً ردود رابط النقر.

كل هذه المسارات مفتوحة عبر CORS (Access-Control-Allow-Origin: *) بلا بيانات اعتماد، وCross-Origin-Resource-Policy: cross-origin.

Android System WebView وChrome من 61، وiOS وiPadOS (Safari وWKWebView) من 12.2، والمتصفحات الحديثة على الحاسوب. ما يغيب في محرّك قديم له بديل: IntersectionObserver ← فحص كل 100 ملّي ثانية؛ aspect-ratio في CSS (قبل iOS 15 وWebView 88) ← padding-top؛ Shadow DOM ← أنماط محصورة؛ sendBeacon ← fetch مع keepalive. المحرّك الذي لا يدعم Promise تُطوى فيه الخانات (أو يبقى data-fallback) ولا يفعل السكربت شيئاً آخر.

كل النقاط عامة. serve وtrack وasset مفتوحة عبر CORS وتجيب OPTIONS؛ أما رابط النقر فيُفتح انتقالاً في المتصفح، لا بطلب fetch.

GET /api/ads/serve

الرد 200: {ok, lang, placement:{id, kind, name, aspect_ratio, width, height}, creatives:[{id, booking_id, lang, image, click_url, click_href, alt, title, body, width, height}], ttl, measure:{request, render}}. click_href رابط التحويل الموقّع (أو null لإبداع بلا رابط)، وbooking_id مهمل ويبقى حتى 2.0، وmeasure يقول أي عدّادين يرسلهما العميل. الأخطاء: 400 invalid_placement و404 unknown_placement و429 rate_limited (مع Retry-After: 60) و503 unavailable.

GET /api/ads/click/{token}

يحوّل (302) إلى رابط المعلن ويحتسب النقرة. الرابط من click_href كما هو، مع معاملات اختيارية يضيفها السكربت: s (الموقع) وpv وi (معرّف الظهور) وsv وt=1 (اختبار) وwd=1 (navigator.webdriver، يُحسب متصفحاً آلياً). الوجهة تُقرأ دائماً من قاعدة البيانات، لا من الرابط. صلاحية الرمز 48 ساعة؛ الرمز القديم يُحوَّل ولا يُحتسب. يعمل التحويل ما دام الحجز حيّاً وحتى يوم بعد انتهائه؛ ولا يعمل أبداً لحجز ملغى أو مرفوض (صفحة 410 محايدة). HEAD يجيب مثل GET ولا يُحتسب. التحميل المسبق (Sec-Purpose أو Purpose: prefetch أو prerender) لا يُحوَّل: يأخذ 503 فارغاً فيتركه المتصفح، وتُحتسب النقرة الحقيقية حين تصل. ولا تُحتسب إلا نقرة انتقل فيها المتصفح إلى الرابط (Sec-Fetch-Mode: navigate وSec-Fetch-Dest: document حين يرسلهما): رابط يُحمَّل صورةً أو سكربتاً أو بـfetch أو داخل إطار يُحوَّل ولا يُحتسب (not_navigation). الترويسات: Cache-Control: no-store وReferrer-Policy: strict-origin-when-cross-origin وX-QiAds-Result.

POST /api/ads/track — الصيغة 2 (من 1.3.0)

{
  "v": 2, "sv": "1.3.0", "site": "superqi", "page": "https://example.com/home", "ref": "https://example.com",
  "pv": "k3j9x0abq2m4z8c1", "now": 1791500000000,
  "events": [
    { "e": "request",  "p": "superqi_homepage_slot", "n": 3, "ts": 1791499999200 },
    { "e": "render",   "p": "superqi_homepage_slot", "m": "<material uuid>", "i": "a1b2c3d4e5f6", "w": 360, "h": 160, "mb": 1, "ts": 1791499999500 },
    { "e": "viewable", "p": "superqi_homepage_slot", "m": "<material uuid>", "i": "a1b2c3d4e5f6", "w": 360, "h": 160, "ts": 1791499999900 }
  ]
}

e واحد من request وrender وviewable وclick (الأخير فقط لإبداع بلا click_href). حتى 20 حدثاً و8 كيلوبايت في الإرسال الواحد؛ والسكربت يقسم الدفعات عند 3.5 كيلوبايت. test:1 للاختبار، وwd:1 حين navigator.webdriver. الحدث الذي يسبق now بأكثر من 15 دقيقة لا يُحتسب. يُرسل الجسم JSON بنوع text/plain (لا يحتاج preflight). الرد 204 مع X-QiAds-Result؛ 400 لطلب غير صالح، و413 لجسم أكبر من الحد، و429 عند تجاوز الحد، و503 إن تعذّرت القاعدة.

POST /api/ads/track — الصيغة 1 (حتى 1.2.1، مقبولة دائماً)

{v:1, event:"impression"|"click", material_id, booking_id, placement_id, site, page, ref, pv, ts} حتى 4 كيلوبايت. event: "impression" تعني مشاهدة فعلية. تُنظَّف page وref كما في الصيغة 2.

GET /api/ads/asset/{material_id}

صورة الإبداع، تُقدَّم فقط أثناء عمل الحجز، وإلا 404 (يُحفظ في كاش الشبكة دقيقة). ?lang=en أو ?lang=ku لصورة تلك اللغة، والعربية إن لم تُرفع؛ وContent-Language تبيّن أيّها أُرسل.