DecideAdItems API

With the DecideAdItems API, you can request/receive selected item lists using our API. You should call the decision API on the inventories you want to serve the Sponsored Product Ads. The properties in a request (items, search_query, and more) in 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.
• 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.

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 for your platform. See the DecideAdIteam API Doc and the MCM Decision API Client Library for JavaScript Github repository for more details.

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.

🚧

Caution

You must integrate item catalog data first before testing the API

DecideAdCreatives API

With the DecideAdCreatives API, you can request/receive selected creative(e.g. image) and corresponding item lists 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.

Detailed values for each field should be pre-arranged with your Moloco representative before the testing/production serving. You need an API key and platform_id specifically for your platform to access the API. Moloco will provide this during integration testing. See the DecideAdCreative API Doc and the MCM Decision API Client Library for JavaScript Github repository for more details.

🚧

Caution

You must integrate the 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 tracker URL by user action at the client(app/web) side. The impression tracker URL should be called when the client renders the image to the inventory.

• (Required) Impression tracker should be called only once upon the first visible moment.
• (Recommended) When 50% of the item image’s pixels are visible or When the top two vertices(corners) of the item’s image are visible, call the impression tracker URL.

🚧

Caution

If the requirement is not followed, 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.

Additional information DecideAdCreatives case

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 URL and item-tracking URL given in the response.