QiAds Web SDKDeveloper guide

qiads.js is one dependency-free script that shows the ads that are live right now on a QiAds placement — a rotating banner, an inline card or a popup — on any web page or inside an app's WebView, and measures them. It is served from the same origin as the ad API: https://qi-ads.com.

What it measures (aggregate counts per Baghdad day; full definitions in Measurement methodology):

What it never does: set or read cookies (one exception: the popup frequency cap on a page without DOM storage, see Privacy), use persistent identifiers, fingerprint the device, collect names, phone numbers or accounts, or send the part of the page URL after ?.

Each ad renders inside Shadow DOM (a <qiads-slot> element in the slot, <qiads-popup> for the popup): your page's styles cannot reach it and it changes nothing else on the page. Engines without Shadow DOM get the ad in the page with styles scoped to .qiads* classes.

Evergreen (recommended)

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

/qiads.js is always the latest 1.x release. It is cached for 5 minutes and revalidated in the background for up to a day, so a fix reaches every page within minutes without any change on your side. No 1.x release breaks what works today (see Versioning policy).

Pinned with Subresource Integrity

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

/sdk/<version>/qiads.js never changes (cached for a year, immutable), so it can be pinned with an SRI hash: the browser refuses the file if a single byte differs. The exact integrity value is printed on the developer guide page and on the admin console's «كود التضمين», from the release file itself. Upgrading is your decision: change the version and the hash together. crossorigin="anonymous" is required for SRI, and the server sends Access-Control-Allow-Origin: * for these files. The previous release stays available for rollback: /sdk/1.2.1/qiads.js.

Loading

The tag runs unchanged inside Android WebView and iOS WKWebView, but the host app owns three things: where clicks open, when the screen is really visible, and which origins it trusts.

WebView settings

Clicks: hand them to the app

Never set data-target="_self" inside an app: the advertiser's page would load in the app's own WebView, next to whatever JavaScript bridge the app exposes. The default _blank is not enough either: on Android (with the default setSupportMultipleWindows(false)) it becomes a navigation that replaces your screen, and WKWebView does nothing unless createWebViewWith is implemented. Take the click instead:

document.addEventListener("qiads:click", function (event) {
  var bridge = window.SuperQiBridge                     // your app's own bridge object
  if (!bridge || !bridge.openExternal || !event.detail.url) return   // no bridge: the link opens as usual
  event.preventDefault()                                // the SDK does not navigate
  bridge.openExternal(event.detail.url)                 // the app opens it in Custom Tabs / SFSafariViewController
})

Cancel only when the bridge is there and there is a URL to hand over: cancelling and then failing to reach the bridge (the page opened in a plain browser, an older app build) loses the click — no navigation and no count. Or through the configuration: QiAds.init({ onClick: function (detail) { if (window.SuperQiBridge && detail.url) { SuperQiBridge.openExternal(detail.url); return false } } }).

detail.url is the QiAds click redirect (https://qi-ads.com/api/ads/click/…). Open it in an in-app browser — Custom Tabs on Android, SFSafariViewController on iOS — and the click is counted when that browser follows the redirect to the advertiser. Never resolve the link with an HTTP client first (OkHttp, URLSession): that click is not the user's, it is classified as a bot, and the user loses the landing page.

When a click does not go through the bridge, intercept the navigation natively:

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   // your pages stay in the WebView
        CustomTabsIntent.Builder().build().launchUrl(view.context, url)
        return true
    }
}

// WKUIDelegate: _blank links
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: every tap on an outside link
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)
}

Restrict the JavaScript bridge to your own origins: WebViewCompat.addWebMessageListener with allowedOriginRules on Android, a check of message.frameInfo.securityOrigin on iOS. A long-press link preview on iOS opens the link without a click event — the click is still counted, because the redirect goes through the QiAds server.

Lifecycle: visibility and refresh

Content-sized WebViews (known limit)

If the WebView is laid out at the full height of its content inside a native scroll view, the page cannot know what is on screen: IntersectionObserver sees every slot as visible, and viewable impressions are overstated. Keep the WebView screen-sized (it scrolls its own content), or tell us — an API for the app to pass its scroll position is on the roadmap.

Allowlists and CSP

Allow https://qi-ads.com for: the script, connections (serve and track), images (the creatives) and navigation (the click redirect /api/ads/click/…, which then sends the user to the advertiser's domain). Mini-program domain lists need the same origin. A CSP example: script-src https://qi-ads.com; connect-src https://qi-ads.com; img-src https://qi-ads.com.

Checklist on real devices

For native screens with no WebView, use the REST API:

Script tag attributes

Boolean attributes (data-test, data-debug, data-observe) are on when present; the values 0, false, no and off turn them off.

Slot attributes

The data-qiads-* alias is read before the short name — useful when a short name clashes with a framework that uses data-format, for example. data-lang has no alias.

Attributes the SDK writes (outputs)

Do not set them yourself or read them as inputs: that is why data-lang has no data-qiads-lang alias — if it had one, the SDK would read back its own output (the Arabic fallback) on refresh and pin it.

window.qiadsConfig and QiAds.init(options)

Precedence: window.qiadsConfig (read at load) ← the tag's data-* attributes win over it ← QiAds.init(options) wins over both from the moment it is called. ?qiads_test=1 and ?qiads_debug=1 in the page URL also turn the two modes on.

QiAds.version                          // "1.3.1"
QiAds.config                           // the current configuration (read only)
QiAds.init(options?)                   // reads the configuration and fills every new [data-qiads]
QiAds.render(target, options?)         // Promise<boolean> — target: an element or a CSS selector
QiAds.popup(placement, options?)       // Promise<boolean>
QiAds.close()                          // closes the open popup
QiAds.destroy(target?)                 // one slot, or with no argument every slot and the popup
QiAds.on(type, fn)                     // listens to an event (see Events)
QiAds.off(type, fn)                    // stops listening
QiAds.refresh(target?)                 // Promise<boolean> — a new impression: new ids, fresh ads
QiAds.setVisible(visible)              // the host app's visibility: false stops measuring and rotation
QiAds.getSlots()                       // the slots on the page: {el, placement, format, state, lang, creatives}
QiAds.getVersion()                     // "1.3.1"

render options: placement, format, limit, rotate, target, fallback, lang, dir, cap, aspect, collapse and page — each option wins over the matching slot attribute.

The command queue works before the script loads and runs once the page is parsed:

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) }) })

// or GPT-style:
window.QiAds = window.QiAds || { cmd: [] }
QiAds.cmd.push(function () { QiAds.refresh() })

Each command is its method's name followed by its arguments; a function in the queue is called with the API. After loading, window.qiads and QiAds.cmd become objects whose push runs the command at once. Every method catches its own errors: an SDK error never reaches your page.

Every event arrives two ways with the same detail: QiAds.on(type, fn), and a DOM event named qiads:<type> that bubbles from the slot element (from document for a popup opened without a slot).

Order for one creative: request → render → impression, then click and close when they happen; empty or error instead of render when the slot cannot be filled.

The detail (event.detail, or the listener's argument):

A click is cancelled by any of: event.preventDefault() on the DOM event, detail.preventDefault(), or returning false from an on("click") listener or from onClick. The SDK then does not navigate, and the app opens detail.url itself, so the click is still counted. A click the browser does not mark as real (isTrusted false, such as a script's el.click()) neither navigates nor fires events.

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

Reserving space (no layout shift): reserve the slot's box at the placement's proportions before the ad arrives. The simplest way is style="aspect-ratio:9/4" on the slot; if your page's CSP refuses style attributes, put it in your stylesheet: [data-qiads="superqi_homepage_slot"]{aspect-ratio:9/4}. Add data-aspect="9/4" so the SDK reserves the space itself in engines without CSS aspect-ratio (a padding-top fallback). Once the server answers, the box takes the placement's actual proportions.

Collapsing: with no ad the slot is hidden (display:none) by default. data-fallback keeps its own content (a house ad, for example), and data-collapse="never" keeps the reserved box with a neutral background so the content below does not move.

Every creative has an Arabic version; an advertiser may add an English and/or a Kurdish one. The landing link is the same for every language. A slot's language is the first recognised value of: lang in QiAds.render, then data-lang on the slot; then data-lang on the tag; then <html lang> (en* → en · ku, ckb*, kmr* → ku · ar* → ar); otherwise ar. An unrecognised value is skipped.

Fallback rule: the requested language's version is shown when an image was uploaded for it, otherwise the same campaign's Arabic version; a campaign never disappears for lack of a translation, and two languages are never mixed in one ad. data-qiads-lang on the slot and creatives[].lang in the serve answer show the language actually served. Direction follows the language shown (rtl for Arabic and Kurdish) unless data-dir is set, and so does the «Ad» badge (إعلان · Ad · ڕیکلام). Figures count per creative, whatever the language.

The terms follow the MRC and IAB guidelines, and they are the same texts the reports and the admin console show:

Measurement details:

We do not collect: the IP address itself, cookies (the server sets none and reads none), names, phone numbers or accounts, advertising ids, the part after ? or #, the full referrer, or location. Once a day's salt is deleted after two days, that day's hashes cannot be linked to an address. The SDK keeps only the last popup time in the browser, in localStorage or sessionStorage, and when storage is disabled in a cookie of the same name on your page's domain. Cloudflare's operational logs may keep request data (address and user agent) for up to 7 days. Details: privacy policy (Arabic).

Test mode — data-test on the tag, ?qiads_test=1 in the page URL, or QiAds.init({ test: true }): everything renders and every event fires, but beacons carry test:1 and the click link carries t=1, so the user is redirected and nothing is counted. The preview page /ads-demo.html is always in test mode.

Debug mode — data-debug, ?qiads_debug=1, or QiAds.init({ debug: true }): logs every step with console.info (visible in chrome://inspect and Safari Web Inspector), outlines every ad, and sends with fetch and keepalive so it can read the server's verdict from the X-QiAds-Result header and print it:

The header is readable from any origin (Access-Control-Expose-Headers), and the click redirect's answers carry it too.

All of these are CORS-open (Access-Control-Allow-Origin: *) without credentials, with Cross-Origin-Resource-Policy: cross-origin.

Android System WebView and Chrome 61+, iOS and iPadOS (Safari and WKWebView) 12.2+, and current desktop browsers. What an old engine lacks has a fallback: IntersectionObserver → a 100 ms check; CSS aspect-ratio (before iOS 15 and WebView 88) → padding-top; Shadow DOM → scoped styles; sendBeacon → fetch with keepalive. In an engine without Promise the slots collapse (or keep their data-fallback) and the SDK does nothing else.

Every endpoint is public. serve, track and asset are CORS-open and answer OPTIONS; the click link is opened as a browser navigation, never with fetch.

GET /api/ads/serve

A 200 answer: {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 is the signed click redirect (or null for a creative without a link), booking_id is deprecated and stays until 2.0, and measure says which two counters the client sends. Errors: 400 invalid_placement, 404 unknown_placement, 429 rate_limited (with Retry-After: 60) and 503 unavailable.

GET /api/ads/click/{token}

Redirects (302) to the advertiser's link and counts the click. The link is click_href as served, with optional parameters the SDK adds: s (site), pv, i (impression id), sv, t=1 (test) and wd=1 (navigator.webdriver, filed as automation). The destination always comes from the database, never from the link. A token is valid for 48 hours; an older one is redirected but not counted. The redirect works while the booking is live and for a day after it ended; never for a cancelled or rejected booking (a neutral 410 page). HEAD answers like GET and counts nothing. A speculative load (Sec-Purpose or Purpose: prefetch or prerender) is not redirected: it gets an empty 503, which the browser discards, so the user's real click reaches the server and is counted. Only a load the browser reports as a navigation to a document (Sec-Fetch-Mode: navigate, Sec-Fetch-Dest: document, when it sends them) counts: the link loaded as an image, script, fetch or inside a frame is redirected but not counted (not_navigation). Headers: Cache-Control: no-store, Referrer-Policy: strict-origin-when-cross-origin and X-QiAds-Result.

POST /api/ads/track — version 2 (from 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 is one of request, render, viewable and click (the last only for a creative without click_href). Up to 20 events and 8 KB per beacon; the SDK splits batches at 3.5 KB. test:1 for testing, wd:1 when navigator.webdriver is true. An event more than 15 minutes older than now is not counted. The JSON body is sent as text/plain (no preflight). The answer is 204 with X-QiAds-Result; 400 for an invalid request, 413 for a body over the limit, 429 when rate-limited, 503 when the database is unavailable.

POST /api/ads/track — version 1 (up to 1.2.1, accepted forever)

{v:1, event:"impression"|"click", material_id, booking_id, placement_id, site, page, ref, pv, ts}, up to 4 KB. event: "impression" means a viewable impression. page and ref are cleaned as in version 2.

GET /api/ads/asset/{material_id}

The creative's image, served only while the booking is live, otherwise 404 (kept in the edge cache for a minute). ?lang=en or ?lang=ku for that language's image, the Arabic one when none was uploaded; Content-Language names the one sent.