6. Ad serving and tracking

Suggest Edits

DecideAdItems API

With the DecideAdItems API, you can request/receive selected item lists using our API. You should call this API on the inventories you want to serve the Sponsored Product Ads. 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 the 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 this 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

Calling trackers

Once you call the Decision API, you will retrieve a list of the ad items or the banner image according to the API you use. As the ad performance reporting is based on ad impressions and clicks, tracking the impressions and clicks of each ad item or banner image is required. To achieve this, MCM provides tracker URLs with the response of Decision API.

  • The ad budget spending is charged on an impression event for CPM campaigns.
  • The ad budget charge for CPC campaigns is based on a click event.

Each item in the DecideAdItems API response has an impression tracker URL(imp_tracker), a click tracker URL(click_tracker), and a tracking ID.

The DecideAdCreatives API response contains a banner image and corresponding items with an impression tracker URL(imp_tracker) and a click tracker URL(click_tracker).

📘

Note

The clients– web browsers, iOS apps, or Android apps –can easily send impressions and clicks information to the Moloco Commerce Media system. The imp_tracker and click_tracker URLs can be called using either an HTTP GET method or an HTTP POST method with no body.

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: [
			https://{platform}-evt.rmp-api.moloco.com/t/i/{platform}?source=2X2GfYlrn299CPDQRD2NzDzn19420CYG3Mfvi6808e0G-4WWoCZSoCp4nDG
		],
		click_trackers: [
			https://{platform}-evt.rmp-api.moloco.com/t/c/{platform}?source=2X2GfYlrn299CPDQRD2NzDzn19420COyzMfvi6808e0G-4WWoCZSoCp4nDG
		],
		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: "<https://storage.googleapis.com/rmp-cdn/platform/{platform}/images/py8lmofm_kg5d4ky.jpeg>"
		imp_trackers: [
			https://{platform}-evt.rmp-api.moloco.com/t/i/{platform}?source=2X2GfYlrn299CPDQRD2NzDzn19420CYG3Mfvi6808e0G
		],
		click_trackers: [
			https://{platform}-evt.rmp-api.moloco.com/t/c/{platform}?source=2X2GfYlrn299CPDQRD2NzDzn19420COyzMfvi6808e0G
		]
	},
	items: [
		{
			item_id: "1111",
			imp_trackers: [
				https://{platform}-evt.rmp-api.moloco.com/t/i/{platform}?source=2X2GfYlrn299CPDQRD2NzDzn19420CYG3Mfvi6808e0G-4WWoCZSoCp4nDG
			],
			click_trackers: [
				https://{platform}-evt.rmp-api.moloco.com/t/c/{platform}?source=2X2GfYlrn299CPDQRD2NzDzn19420COyzMfvi6808e0G-4WWoCZSoCp4nDG
			],
		},
		...
	]
}

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.

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.

Graceful fallback behavior

Although a client may request 20 items, Moloco Commerce Media may respond with less than 20 items or even 0. Moloco does not guarantee the requested number of items can always be filled; we recommend the client have a fallback plan for such a case.

Fallback Options for Sponsored Product

  • Decide not to render the inventory if the number of items returned is 0, or an error happened during the API call.
  • Display the sponsored ad items that Moloco sends, even if they are smaller than the requested amount.
  • Fill inventories by using organic recommendation logic.

Fallback Options for Sponsored Banner

  • Decide not to render the inventory if the response doesn’t have any image response or error happened during the API call.
  • Display in-house banner advertisements.

Updated about 1 month ago