Royal Air Maroc · IMD advertising integration
This page describes how to show IMD advertising inside the Royal Air Maroc onboard portal and apps. All requests go to one base URL:
https://ram.demo.imd-nl.com/api/
There are two ways to integrate:
IMD provides the section UUID(s) and the zones for each placement. You need these values for both integration options.
A. JavaScript SDK
A1. Load the IMD engine
Add the engine as a JavaScript module. The engine derives its base URL
from this src, so always load it from
ram.demo.imd-nl.com/api: assets and tracking calls go to
the same host.
<script
defer="defer"
type="module"
src="https://ram.demo.imd-nl.com/api/assets?path=engine.js"></script>
A2. Language and flight targeting
Define window.imd with a language() and/or
flight() method before loading the
engine. The engine calls these functions on every ad request, so they
may return live values from the onboard system.
<script>
window.imd = {
language: function () {
return "fr";
},
flight: function () {
return {
flightNumber: "AT200",
departure: "CMN",
arrival: "JFK"
};
}
};
</script>
<script defer="defer" type="module"
src="https://ram.demo.imd-nl.com/api/assets?path=engine.js"></script>
| Property | Parameter | Description | Example |
|---|---|---|---|
language() |
l |
Passenger interface language, two-letter ISO 639-1 code | fr, ar, en |
flight().flightNumber |
fn |
IATA flight number | AT200 |
flight().departure |
dep |
Departure airport IATA code | CMN |
flight().arrival |
arr |
Arrival airport IATA code | JFK |
All properties are optional. Values that are undefined or
null are skipped.
A3. Placeholder attributes
The engine scans every <ins> inside
<body> and reads its configuration from these
data-* attributes. No custom CSS is needed on the
<ins> element itself.
| Attribute | Required | Description | Example |
|---|---|---|---|
data-type |
Yes | banner for display ads, vast for video pre-rolls. |
banner |
data-format |
Yes |
Format identifier: 728x90 (IAB Leaderboard),
300x250 (IAB MPU) or video-pre-roll.
|
728x90 |
data-section |
Yes | Section UUID provided by IMD. | f97145ba-c32e-44eb-9fed-b4b426a3ea9b |
data-zone |
Yes |
Placement within the section: 1 above the fold,
2 mid page, 3 below the fold. If
unsure, use 1.
|
1 |
data-width |
Yes | Slot width as a CSS size, e.g. 100%. |
100% |
data-height |
Yes | Slot height as a CSS size, e.g. auto. |
auto |
data-zindex |
No | Stacking order of the rendered banner image. | 1 |
data-id |
Video only | ID of the content <video> element the pre-roll plays in front of. |
content-player |
data-action |
Video only |
Name of a global function the engine calls when the pre-roll has
finished, is skipped, or when no ad is available. Dot notation
is supported (player.resume).
|
startContent |
A4. IAB Leaderboard (728×90)
<ins
data-type="banner"
data-format="728x90"
data-section="f97145ba-c32e-44eb-9fed-b4b426a3ea9b"
data-zone="1"
data-width="100%"
data-height="auto"
data-zindex="1"
></ins>
Rendered result:
A5. IAB MPU (300×250)
<ins
data-type="banner"
data-format="300x250"
data-section="f97145ba-c32e-44eb-9fed-b4b426a3ea9b"
data-zone="2"
data-width="100%"
data-height="auto"
data-zindex="1"
></ins>
Rendered result:
A6. Video pre-roll
Place a vast placeholder next to the content player. The
engine hides the content player while the ad plays, shows an
“Ad” countdown and (when configured) a skip button, and
then calls your data-action function so you can start
the content.
<div style="max-width: 640px; aspect-ratio: 16 / 9">
<video id="content-player" controls playsinline src="/movies/feature.mp4"></video>
<ins
data-type="vast"
data-format="video-pre-roll"
data-section="f97145ba-c32e-44eb-9fed-b4b426a3ea9b"
data-zone="1"
data-width="640"
data-height="360"
data-id="content-player"
data-action="startContent"
></ins>
</div>
<script>
function startContent() {
document.getElementById("content-player").play();
}
</script>
The callback is also called when no pre-roll is available, so always
start the content from data-action rather than directly.
A7. Single-page applications and behaviour
-
The engine rescans the page every second.
<ins>elements added later (e.g. after a route change) are filled automatically; no extra call is needed. -
On
popstatethe banners are reset, so a new impression is counted for the new page. - Banners can rotate: when IMD configures a rotation interval, the engine requests a new ad in the same slot after that interval.
- Impressions are counted once per ad, when at least half of the banner is in the viewport and the page is not in fullscreen.
-
During a passenger announcement, call
window.internal_imd.announcement(true)to pause IMD video, andannouncement(false)to resume.
B. REST API
B1. When to use the API
Use the API when the SDK cannot run: a native iOS/Android app, a set-top or seatback client, or a custom video player. The API is the same one the SDK uses; this section describes what the SDK does so you can do the same.
- Base URL:
https://ram.demo.imd-nl.com/api/ - No authentication header is needed; CORS is open for browser clients.
- Requests with a body use
Content-Type: application/json. - Timestamps are ISO 8601 in UTC, e.g.
2026-11-20T09:15:00.000Z.
B2. Ad lifecycle
- Identify the passenger device – create a stable, anonymous user ID (
u). - Register the session –
POST /u, once per session. - Request an ad per slot –
GET /awith a fresh correlation ID.200returns an ad,404means no ad: hide the slot (or start the content for video). - Render the creative from
downloadUri, with the privacy-policy link. - Count the impression –
POST /vonce, when the ad is at least 50% visible. - Handle clicks –
POST /c, then open the click target. - Video only – report progress with
POST /vq. - Rotate – if the ad has a
rotationvalue, go back to step 3 after that many seconds.
B3. Identifiers and shared fields
These short field names are used throughout the API:
| Field | Meaning | Rules |
|---|---|---|
u |
User ID | Non-empty string, stable for one device/passenger during the flight. Used for frequency capping. The SDK uses a browser fingerprint hash; in an app use a random ID stored on the device. Never send personal data. |
s |
Section ID | UUID provided by IMD. |
z |
Zone | Integer ≥ 1 (query string on /a, number in JSON bodies). |
f |
Format | 728x90, 300x250 or video-pre-roll. |
c |
Correlation ID | New UUID v4 for every GET /a. |
l |
Language | Optional, exactly two letters (ISO 639-1). |
fn, dep, arr |
Flight data | Optional. Flight number and IATA airport codes. Send the same values on every call. |
a, v |
Ad ID, variant ID | Returned by GET /a; send them back on /v, /c and /vq. |
p |
Page | Full URL of the page showing the ad. In a native app, a URI that identifies the screen, e.g. ram-app://entertainment/home. |
d |
Event time | ISO 8601 timestamp of the event. |
B4. Register the session – POST /u
Call once per passenger session, before the first ad request.
POST /api/u HTTP/1.1
Host: ram.demo.imd-nl.com
Content-Type: application/json
{
"u": "3f9a1c0e6b7d4e21a8c5f0d2b4e6a7c9",
"fn": "AT200",
"dep": "CMN",
"arr": "JFK"
}
Response: 204 No Content.
B5. Request an ad – GET /a
GET /api/a?s=f97145ba-c32e-44eb-9fed-b4b426a3ea9b&z=1&f=728x90
&u=3f9a1c0e6b7d4e21a8c5f0d2b4e6a7c9
&c=6f1d2a7e-9b3c-4f8e-a1d2-3c4b5e6f7a8b
&l=fr&fn=AT200&dep=CMN&arr=JFK HTTP/1.1
Host: ram.demo.imd-nl.com
Response 200 OK:
{
"a": "c2d6e3f0-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"v": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
"m": [
{ "name": "downloadUri", "value": "https://ram.demo.imd-nl.com/api/assets?path=..." },
{ "name": "width", "value": "728" },
{ "name": "height", "value": "90" },
{ "name": "click", "value": "https://www.example.com/offer" },
{ "name": "rotation", "value": "30" }
]
}
Read the creative and its behaviour from the m (metadata) list:
| Metadata | Always present | Meaning |
|---|---|---|
downloadUri |
Yes | URL of the image (banner) or video file (pre-roll). |
width, height |
No | Native size of the creative in pixels. |
click |
No | Click target, see B7. Without it the ad is not clickable. |
rotation |
No | Seconds after which the slot should request a new ad. |
skip |
No (video) | Seconds after which the passenger may skip the pre-roll. |
Status codes:
200– ad selected.404– no ad for this slot right now. Hide the slot; for video, start the content.400– invalid parameter (e.g. section or correlation ID not a UUID, zone < 1, language not two letters).
Display requirements. Show a “privacy policy” link on every
ad that opens https://ram.demo.imd-nl.com/api/fs/privacy-policy.html.
Label video ads as “Ad” with the remaining time, and only offer
“Skip” after the skip seconds have passed.
B6. Count the impression – POST /v
Send once per ad (per GET /a response), as soon as at
least half of the banner is visible on screen. Do not count ads that
are hidden, off-screen or behind a fullscreen player.
POST /api/v HTTP/1.1
Host: ram.demo.imd-nl.com
Content-Type: application/json
{
"a": "c2d6e3f0-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"v": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
"s": "f97145ba-c32e-44eb-9fed-b4b426a3ea9b",
"z": 1,
"u": "3f9a1c0e6b7d4e21a8c5f0d2b4e6a7c9",
"d": "2026-11-20T09:15:00.000Z",
"p": "https://portal.example/entertainment",
"l": "fr",
"fn": "AT200",
"dep": "CMN",
"arr": "JFK"
}
Response: 204 No Content. Required: a, v, s, z, u, d, p.
B7. Handle a click – POST /c
Register the click with the same body as /v, then open the target:
POST /api/c HTTP/1.1
Host: ram.demo.imd-nl.com
Content-Type: application/json
{ "a": "...", "v": "...", "s": "...", "z": 1, "u": "...", "d": "...", "p": "...", "l": "fr" }
Then resolve the click value like the SDK does:
click value |
Action |
|---|---|
Starts with http |
Open the URL in a new tab / external browser / in-app browser. |
Relative path ending in .js |
Interactive ad (web only): import
{base}assets?path={click} as a module and call its
exported load(). In a native app, open the ad in a
web view with the SDK instead.
|
| Any other relative path |
Advertiser micro-site hosted by the engine. Open
{base}fs/{click}?l={l}&a={a}&s={s}&u={u}&z={z}&v={v}
in a new tab or web view.
|
B8. Video progress – POST /vq
For pre-rolls, report each event once with the same body as
/v plus a q field. A video ad has no
separate /v call: videoStart is the
impression.
{ "a": "...", "v": "...", "s": "...", "z": 1, "u": "...", "d": "...", "p": "...",
"l": "fr", "q": "videoFirstQuartile" }
q |
When |
|---|---|
videoStart | Playback has actually started. |
videoFirstQuartile | 25% of the duration played. |
videoMidpoint | 50% played. |
videoThirdQuartile | 75% played. |
videoComplete | Playback ended. |
skip | Passenger pressed “Skip”. |
click | Passenger clicked the video (send POST /c as well). |
After videoComplete or skip, remove the ad
player and start the content.
B9. Minimal JavaScript client
A compact example of the lifecycle above for one banner slot, without the SDK:
const BASE = "https://ram.demo.imd-nl.com/api/";
const user = localStorage.imdUser ??= crypto.randomUUID().replaceAll("-", "");
const flight = { fn: "AT200", dep: "CMN", arr: "JFK" };
const lang = "fr";
async function post(path, body) {
await fetch(BASE + path, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
}
async function showBanner(slot, { section, zone, format }) {
const q = new URLSearchParams({
s: section, z: zone, f: format, u: user, c: crypto.randomUUID(), l: lang, ...flight,
});
const res = await fetch(BASE + "a?" + q);
if (res.status === 404) { slot.hidden = true; return; }
const ad = await res.json();
const meta = Object.fromEntries(ad.m.map((m) => [m.name, m.value]));
const event = () => ({
a: ad.a, v: ad.v, s: section, z: zone, u: user,
d: new Date().toISOString(), p: location.href, l: lang, ...flight,
});
const img = new Image();
img.src = meta.downloadUri;
img.style.width = "100%";
if (meta.click) {
img.style.cursor = "pointer";
img.onclick = () => {
post("c", event());
const target = meta.click.startsWith("http")
? meta.click
: `${BASE}fs/${meta.click}?l=${lang}&a=${ad.a}&s=${section}&u=${user}&z=${zone}&v=${ad.v}`;
window.open(target, "_blank");
};
}
const privacy = document.createElement("a");
privacy.href = BASE + "fs/privacy-policy.html";
privacy.target = "_blank";
privacy.textContent = "privacy policy";
slot.replaceChildren(img, privacy);
// Impression: once, when at least 50% is visible.
const io = new IntersectionObserver(([entry]) => {
if (entry.isIntersecting) { post("v", event()); io.disconnect(); }
}, { threshold: 0.5 });
io.observe(slot);
// Rotation
if (meta.rotation) {
setTimeout(() => showBanner(slot, { section, zone, format }), meta.rotation * 1000);
}
}
if (!sessionStorage.imdRegistered) {
post("u", { u: user, ...flight });
sessionStorage.imdRegistered = "1";
}
showBanner(document.getElementById("top-banner"), {
section: "f97145ba-c32e-44eb-9fed-b4b426a3ea9b", zone: 1, format: "728x90",
});
B10. Quick test with curl
curl -i "https://ram.demo.imd-nl.com/api/a?s=f97145ba-c32e-44eb-9fed-b4b426a3ea9b&z=1&f=728x90&u=test-device&c=$(uuidgen)&l=en"
A 404 is a valid answer: there is no active campaign for
that section, zone and format. Ask IMD to schedule a test campaign.
Go-live checklist
- Section UUID(s) and zones received from IMD for every placement.
- Language and flight data are passed (SDK:
window.imd; API:l,fn,dep,arr). - Empty slots (
404) are hidden and video content still starts. - Every ad shows the privacy-policy link; video ads show the “Ad” label.
- Impressions are sent once per ad and only when visible (API integrations).
- Clicks are registered before the target is opened (API integrations).
- The portal allows outgoing requests to
ram.demo.imd-nl.com(firewall / walled garden / CSPscript-src,img-src,media-src,connect-src).