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
- Log in to your dashboard.
- Navigate to the Services section from the side bar.
- If a service already exists, select it. Otherwise:
- Create a new service.
- Provide all necessary service information, which will be visible to advertisers.
- After creating or selecting a service, click on it.
- 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 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: " \
-H "X-Forwarded-For: " \
-H "X-Real-IP: "
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: " \
-H "X-Forwarded-For: " \
-H "X-Real-IP: "
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: " \
-H "X-Forwarded-For: " \
-H "X-Real-IP: "
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: " \
-H "X-Forwarded-For: " \
-H "X-Real-IP: "
Response Sample
Status Code: 200 OK
{
"message": "CLICK received"
}