DecideAdItems API

With the Decision API, you can request/receive selected item lists. You should call the decision API on the inventories you want to serve Sponsored Product Ads. The properties in a request (items, search_query, and more) inside the inventory object may vary depending on the ad serving scenarios.

• inventory_id: A unique identifier for the platform's inventory. This will be used to calculate metrics per inventory.
  
  
• num_items: Number of items you want to receive as an auction result.
  
  
  • We recommend using a maximum of 50 items per request.
    
    
• items: Required for PDP inventories. The main item IDs of the page should be included.
• search_query: Required for search result inventories. The search query string should be given.

DecideAdCreatives API

With the DecideAdCreatives API, you can request/receive selected creative(e.g. image) and corresponding item lists (Maximum of 200 items) using our API. You should call the decision API on the inventories you want to serve Sponsored Banner type Ads. Properties (Items, search_query, and more) in the ‘inventory’ object may vary depending on the ad serving scenarios.

• inventory_id: Required for all inventories. A unique identifier for the inventory that the platform manages. This will be used to calculate metrics per inventory.
• items: Required for PDP inventories. The main item IDs of the page. For example, a homepage inventory may not have any main items, but a product-detail-page inventory will have one main item.
• search_query: Required for search result inventories. The search query string should be given.

Configuration

Detailed values for each property should be pre-arranged with your Moloco representative. To access the API, an API key and platform_id are required. API keys are created and managed through the Stand Alone Campaign Manger portal under Credential Management. Please see DecideAdIteam API and the MCM Decision API Client Library for JavaScript Github repository for more details and examples.

To enable API integration tests, Moloco provides two platform identifiers: one for testing and one for actual ingestion. Using the test Platform ID, you may send test requests and receive test responses filled with the random items selected from your catalog. Your MCM representative will provide you with the platform_ids during the initial onboarding.

🚧

Caution

You must integrate item catalog data first before testing the API

Response example for DecideAdItems API

[
	{
		item_id: "22723115",
		auction_result: {
			ad_account_id: "001",
			campaign_id: "MMdY9pyO8aph2izF",
			win_price: {
				currency: "USD",
				amount_micro: "100000"
			}
		},
		imp_trackers: [
			<imp_tracker_url>
		],
		click_trackers: [
			<click_tracker_url>
		],
		track_id: "2X2GfYlrn299CPDQRD2NzDzn19420CYG39Y-4WWoCZSoCp4nDG"
		}
	},
	{
	...
	}
]

Response example for DecideAdCreatives API

{
	auction_result: {
		ad_account_id: "001",
		campaign_id: "MMdY9pyO8aph2izF",
		win_price: {
			currency: "USD",
			amount_micro: "100000"
		}
	},
	banner: {
		creative_id: "8lzo4lLQOPpzyo0c",
		image_url: "<image_url>"
		imp_trackers: [
			<imp_tracker_url>
		],
		click_trackers: [
			<click_tracker_url>
		]
	},
	items: [
		{
			item_id: "1111",
			imp_trackers: [
				<imp_tracker_url>
			],
			click_trackers: [
				<click_tracker_url>
			],
		},
		...
	]
}

Calling the tracker URL

After implementing the Decision API, the next step you should take is to call the impression tracker URL by user action at the client(app/web) side. The impression tracker URL should be called when the client renders the image.

• Call the impression tracker URL a single time when the image is displayed.
• We recommend calling the URL when 50% of the item image’s pixels are visible or when the top two vertices(corners) of the item’s image are visible.

🚧

Caution

If the impression tracker URL is called more than once, the number of clicks may exceed the number of impressions.

The click tracker URL should be called when the user clicks the ad. These URLs can be called asynchronously. For more information please see Calling trackers.

Calling DecideAdCreatives URLs

In the DecideAdCreative’s bidding process, we select campaigns by auction. The resulting banner & items are the property of the selected campaign. For impressions and clicks, banners and items are tracked separately. When an impression or click occurs for each, the customer must call the banner tracking URLs and the item tracking URLs provided in the response.