Sponsored Products API

Request and display sponsored product ads.

Request Structure

Required Fields

Field	Type	Description
id	string	Unique request identifier
number_of_prods	integer	Number of products requested
user.id	string	User ID from cookie (base64 encoded)

Optional Fields

Field	Type	Description
bvendor	array[string]	Brands to exclude
site.page	string	Current page URL
site.cat	array[string]	Categories (most important first)
site.keyword	string	Search keyword
device.ua	string	Browser User-Agent
device.ip	string	User IP address
device.w	integer	Screen width in pixels
device.h	integer	Screen height in pixels

Response Structure

Field	Type	Description
gtin	string	Product ID (GTIN/SKU)
pos	integer	Position in list (1 = highest)
pixel_view	string	URL to call when product is visible
pixel_click_nordr	string	URL to call on click (preferred)
pixel_click	string	URL to call on click (with redirect)
advertiser	string	Advertiser name
behalf_of	string	Sponsor name (if different)

Example: Category Page

Request

<?php
$placement_code = 'your_placement_id';
$token = 'your_api_key';
$user_id = get_user_id();

$data = [
  'id' => 'category_page_' . time(),
  'number_of_prods' => 3,
  'user' => [
    'id' => $user_id,
  ],
  'bvendor' => [],
  'site' => [
    'page' => $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
    'cat' => ['Obuwie', 'Sneakers'],
    'keyword' => '',
  ],
  'device' => [
    'ua' => $_SERVER['HTTP_USER_AGENT'],
    'ip' => $_SERVER['REMOTE_ADDR'],
    'w' => 1920,
    'h' => 1080
  ],
];

$ch = curl_init('https://delivery.mageads.com/products?pc=' . $placement_code);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_TIMEOUT_MS, 500);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
?>

Response

{
  "id": "category_page_12345",
  "sponsored_products": [
    {
      "gtin": "product-id-1",
      "pos": 1,
      "pixel_view": "https://tracking.mageads.com/view?id=abc123",
      "pixel_click": "https://tracking.mageads.com/click?redirect=true",
      "pixel_click_nordr": "https://tracking.mageads.com/click?redirect=false",
      "advertiser": "Brand Name",
      "behalf_of": "Sponsor Name"
    }
  ]
}

Implementation

Display Sponsored Products

if (!empty($result['sponsored_products'])) {
  foreach ($result['sponsored_products'] as $sponsored) {
    $product = get_product_by_gtin($sponsored['gtin']);
    if ($product) {
      display_sponsored_product($product, $sponsored);
    }
  }
}

Product Display with Tracking

function display_sponsored_product($product, $sponsored_data) {
?>
<div class="product-item sponsored" data-gtin="<?php echo $product->gtin; ?>">
  <span class="badge-sponsored">Sponsorowane</span>
  
  <img src="<?php echo $product->image; ?>" alt="<?php echo $product->name; ?>">
  <h3><?php echo $product->name; ?></h3>
  <p class="price"><?php echo $product->price; ?> zł</p>
  
  <!-- View tracking pixel -->
  <img src="<?php echo $sponsored_data['pixel_view']; ?>"
       width="1" height="1" style="display:none;" alt="" />
  
  <!-- Click tracking -->
  <a href="<?php echo $product->url; ?>"
     onclick="trackClick('<?php echo $sponsored_data['pixel_click_nordr']; ?>')">
    Zobacz produkt
  </a>
</div>
<?php
}
?>

<script>
function trackClick(pixelUrl) {
  fetch(pixelUrl, { method: 'GET', mode: 'no-cors' });
}
</script>

Use Cases

Search Page

'site' => [
  'page' => 'https://example.com/?s=buty',
  'cat' => [],
  'keyword' => 'buty'
]

Home Page

'site' => [
  'page' => 'https://example.com',
  'cat' => [],
  'keyword' => ''
]

Product Page (Related Products)

'site' => [
  'page' => 'https://example.com/product/nike-air-max',
  'cat' => ['Obuwie', 'Sneakers'],
  'keyword' => ''
]

Best Practices

• Always display "Sponsorowane" badge
• Respect pos field for positioning
• Call pixel_view when product is visible in viewport
• Call pixel_click_nordr on product click
• Set 400-500ms timeout