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:

A. JavaScript SDK (recommended)

Load engine.js and place <ins> placeholders in your HTML. The SDK requests, renders, rotates and measures the ads for you.

For web pages and web views.

B. REST API (direct)

Call the ad engine endpoints yourself and render the creative in your own components. You are then responsible for impression, click and video tracking.

For native apps, custom video players or frameworks where the SDK does not fit.

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

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.

B2. Ad lifecycle

  1. Identify the passenger device – create a stable, anonymous user ID (u).
  2. Register the session – POST /u, once per session.
  3. Request an ad per slot – GET /a with a fresh correlation ID. 200 returns an ad, 404 means no ad: hide the slot (or start the content for video).
  4. Render the creative from downloadUri, with the privacy-policy link.
  5. Count the impression – POST /v once, when the ad is at least 50% visible.
  6. Handle clicks – POST /c, then open the click target.
  7. Video only – report progress with POST /vq.
  8. Rotate – if the ad has a rotation value, 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:

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
videoStartPlayback has actually started.
videoFirstQuartile25% of the duration played.
videoMidpoint50% played.
videoThirdQuartile75% played.
videoCompletePlayback ended.
skipPassenger pressed “Skip”.
clickPassenger 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