Quantum Retail Media documentation

A Comprehensive Guide

Integration for Quantum Ad Server

Introduction

This guide explains how to integrate with Quantum Ad Server to fetch ad campaigns and handle ad events. Developers can send requests to the service endpoint and receive ad information for display. This document includes steps for setup, sample request payloads, and sample code snippets for cURL, React, and Flutter.

Steps

Step 1: Create or Select a Service

  1. Log in to your dashboard.
  2. Navigate to the Services section from the side bar.
  3. If a service already exists, select it. Otherwise:
    1. Create a new service.
    2. Provide all necessary service information, which will be visible to advertisers.
  4. After creating or selecting a service, click on it.
  5. In the popup window, locate the Integration box. This contains the endpoint link for fetching ads.

Example:

				
					POST https://api.engine.quantums.com.sa/s/m/{serviceId}

				
			

Step 2: Send a Request to Fetch Ads

Endpoint

				
					POST https://api.engine.quantums.com.sa/s/m/{serviceId}

				
			

Request Body

				
					{
  "keywords": "",
  "dataKeys": {}
}
				
			

Sample Response

				
					{
  "campaigns": [
    {
      "aid": "673c6c4ad2444de53edcfbdf",
      "cid": "673c6c4ad2444de53edcfbf5",
      "type": "VIDEO",
      "mediaUrl": "https://d23gtappibzheq.cloudfront.net/1732013129741_1732013128841.mp4",
      "mediaLength": -1,
      "redirectUrl": "http://www.almarai.com/en",
      "start": "https://api.engine.quantums.com.sa/s/r/s?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b",
      "pause": "https://api.engine.quantums.com.sa/s/r/p?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b",
      "impress": "https://api.engine.quantums.com.sa/s/r/i?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b",
      "click": "https://api.engine.quantums.com.sa/s/r/c?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b"
    }
  ]
}
				
			

Response Breakdown

Field Description
type Ad type: VIDEO.
mediaUrl URL of the media file (e.g., video or image).
mediaLength Duration of the video in seconds (-1 if not specified).
redirectUrl URL to redirect users upon ad click.
start API endpoint to call when the ad starts playing.
impress API endpoint to call to register an impression.
click API endpoint to call when the user clicks the ad.

Code Examples

Using cURL

				
					# Using cURL to send a POST request to the API endpoint
curl -X POST https://api.engine.quantums.com.sa/s/m/{serviceId} \

# Specifying the Content-Type header to indicate the request body format is JSON
-H "Content-Type: application/json" \

# Adding custom headers to include user agent and client IP information
-H "User-Agent: {userAgent}" \       # Specifies the user agent string for the request
-H "Client-IP: {clientIP}" \         # Represents the client IP making the request
-H "Forwarded: for={clientIP}" \     # Conveys the originating IP address in a proxy-friendly format

# Providing the request body as JSON data
-d '{
  "keywords": "",   # Example keyword field (currently empty, can be updated as needed)
  "dataKeys": {}    # Example dataKeys field (currently an empty object, meant to hold key-value pairs)
}'

				
			

Using React

				
					// Importing the Axios library for making HTTP requests
import axios from 'axios';

// Asynchronous function to fetch ads for a specific service
const fetchAds = async (serviceId) => {
  // Constructing the API endpoint URL dynamically using the provided service ID
  const url = `https://api.engine.quantums.com.sa/s/m/${serviceId}`;

  // Defining the body of the POST request
  const requestBody = {
    keywords: "",   // Example keyword field (currently empty)
    dataKeys: {}    // Example dataKeys field (currently an empty object)
  };

  // Defining custom headers for the HTTP request
  const headers = {
    'User-Agent': userAgent,       // Specifies the user agent string (e.g., browser or app identifier) for the request
    'Client-IP': clientIP,         // Represents the direct IP address of the client making the request
    'Forwarded': `for=${clientIP}` // Conveys proxy information with the originating IP address
  };

  try {
    // Sending a POST request to the specified URL with headers and request body
    const response = await axios.post(url, requestBody, { headers });

    // Logging the response data to the console if the request is successful
    console.log('Ad Response:', response.data);
  } catch (error) {
    // Catching and logging any errors that occur during the request
    console.error('Error fetching ads:', error);
  }
};

// Calling the function with a placeholder service ID
fetchAds('yourServiceId');

				
			

Using Flutter (Dart)

				
					// Importing the Dart library for JSON encoding and decoding
import 'dart:convert';

// Importing the HTTP package for making API calls
import 'package:http/http.dart' as http;

// A function to fetch ads for a specific service
Future<void> fetchAds(String serviceId) async {
  // Constructing the API endpoint URL with the provided service ID
  final url = Uri.parse('https://api.engine.quantums.com.sa/s/m/$serviceId');

  // Setting the headers for the HTTP POST request
  final headers = {
    'Content-Type': 'application/json', // Specifies the format of the request body
    'User-Agent': userAgent,            // Identifies the client making the request
    'Client-IP': clientIP,              // Represents the IP address of the client
    'Forwarded': 'for=$clientIP'        // Conveys proxy information including the client's IP address
  };

  // Preparing the body of the request as a JSON-encoded string
  final body = jsonEncode({
    "keywords": "",  // Example keyword field (currently empty)
    "dataKeys": {}   // Example dataKeys field (currently an empty object)
  });

  try {
    // Sending the POST request to the specified URL with headers and body
    final response = await http.post(url, headers: headers, body: body);

    // Checking if the response status code indicates success (200 OK)
    if (response.statusCode == 200) {
      // Decoding the JSON response body into a Dart object
      final data = jsonDecode(response.body);

      // Printing the response data to the console
      print('Ad Response: $data');
    } else {
      // Printing an error message if the response status code is not 200
      print('Error: ${response.statusCode}');
    }
  } catch (e) {
    // Handling any exceptions that occur during the API request
    print('Request failed: $e');
  }
}

// Calling the function with a placeholder service ID
fetchAds('yourServiceId');

				
			

Required Headers

				
					// Defining HTTP headers for the request
const headers = {
  'user-agent': userAgent,       // Specifies the user agent string (e.g., browser, android, iphone, ipad, etc...) for the request
  'X-Forwarded-For': clientIP,  // Indicates the originating client IP address
  'X-Real-IP': clientIP         // Provides the real client IP address (alternative to X-Forwarded-For)
};

				
			

Ad Event Tracking

Use the following APIs to track ad events:

Event Endpoint Example
Start https://api.engine.quantums.com.sa/s/r/s?aid={aid}&pid={pid}&rid={rid}
Impress https://api.engine.quantums.com.sa/s/r/i?aid={aid}&pid={pid}&rid={rid}
Click https://api.engine.quantums.com.sa/s/r/c?aid={aid}&pid={pid}&rid={rid}

Example: Sending an Impression Request

				
					curl -X GET "https://api.engine.quantums.com.sa/s/r/i?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b"

				
			

Video Request Hooks

This endpoint registers an impression, start, pause and click for the specified ad. The complete URL provided below is included in the response from the campaign.

Parameters Endpoint Example
aid The Ads ID.
pid The Publisher ID
rid The Request ID

Request to Register Impression

				
					GET ttps://api.engine.quantums.com.sa/s/r/i?aid={AdID}&pid={PublisherID}&rid={RequestID}

				
			
				
					curl -X GET "https://api.engine.quantums.com.sa/s/r/i?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b" \
-H "user-agent: <userAgent>" \
-H "X-Forwarded-For: <clientIP>" \
-H "X-Real-IP: <clientIP>"
				
			

Response Sample

				
					Status Code: 200 OK
{
    "message": "IMPRESSION received"
}
				
			

Request to Register video start

				
					GET ttps://api.engine.quantums.com.sa/s/r/s?aid={AdID}&pid={PublisherID}&rid={RequestID}

				
			
				
					curl -X GET "https://api.engine.quantums.com.sa/s/r/s?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b" \
-H "user-agent: <userAgent>" \
-H "X-Forwarded-For: <clientIP>" \
-H "X-Real-IP: <clientIP>"
				
			

Response Sample

				
					Status Code: 200 OK
{
    "message": "IMPRESSION_START received"
}
				
			

Request to Register Pause

				
					GET ttps://api.engine.quantums.com.sa/s/r/p?aid={AdID}&pid={PublisherID}&rid={RequestID}

				
			
				
					curl -X GET "https://api.engine.quantums.com.sa/s/r/p?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b" \
-H "user-agent: <userAgent>" \
-H "X-Forwarded-For: <clientIP>" \
-H "X-Real-IP: <clientIP>"
				
			

Response Sample

				
					Status Code: 200 OK
{
    "message": "IMPRESSION_SKIPPED received"
}
				
			

Request to Register Click

				
					GET ttps://api.engine.quantums.com.sa/s/r/c?aid={AdID}&pid={PublisherID}&rid={RequestID}

				
			
				
					curl -X GET "https://api.engine.quantums.com.sa/s/r/c?aid=673c6c4ad2444de53edcfbdf&pid=66a8b57c98095a66e1af81af&rid=6742a53387c932b9ae77f39b" \
-H "user-agent: <userAgent>" \
-H "X-Forwarded-For: <clientIP>" \
-H "X-Real-IP: <clientIP>"
				
			

Response Sample

				
					Status Code: 200 OK
{
    "message": "CLICK received"
}