Build your own campaign manager
If you have UI/UX requirements specific to your business/application domain, you can build a custom campaign manager application on top of Moloco’s Management API. The management API allows you to perform ad campaign-related operations such as creating, updating and managing ad campaigns.
Prerequisites
The Management API requires an API key, please review the API Key and SSO credential management guide for information on generating an API key to programmatically access the API. This API key will be used to perform all management operations.
Limitations
End-user authentication, authorization, and management:
- Please use your existing Single Sign On solution to implement these features.
Notifications:
- Platform owners must handle their own user notifications.
Change History:
- The
changed by
field cannot be personalized. This field will only display theSystem
account.
Uploading creatives and image assets
Sponsored Brands and Sponsored Banner campaigns have unique methods for uploading creatives or image assets. You must use the corresponding upload method that matches your campaign type. Please see the information below to choose the correct upload method.
Sponsored Banner creative uploading methods
We provide two ways to upload creatives for Sponsored Banner campaigns:
- Option 1: Upload the file using Moloco’s CDN solution
- Option 2: Upload by CDN URL using your own CDN solution.
Use
multipart/form-data
Content-type to support sending both File and JSON when making CreateImageAsset API requests. Do not useapplication/json
Supported image formats
Image Format | Default Maximum File Size |
---|---|
JPG/JPEG, PNG, WEBP | 1MB / 1024KB |
GIF | 3MB / 3072KB |
Maximum Image File Size
Maximum image file size is configurable at the platform level, if you require a larger image file size or additional image formats please contact your Moloco representative.
Option 1: Upload by File
There are two keys named file
, and creative
.
- The file must be uploaded in the key named
file
. If the keyfile
is not used, the request will fail to parse the upload properly. - The creative asset’s metadata must be included as json value in the key named
creative
. There are additional fields for the request, such asad_account_id
,title
, andtype
(IMAGE
). See the CreateCreative API reference for more details.
Option 2: Upload by CDN URL
When using your own CDN solution, use only the creative
key with JSON format.
Use only one option when uploading creatives: either
file
orcreative.image_source
(JSON content). These methods cannot be used together in the same request.
{
"ad_account_id": "test_ad_account",
"title": "test_title",
"type": "IMAGE",
"image_source": {
"url": "https://storage.googleapis.com/rmp-cdn-test/platform/MOLOCO_PORTAL_DEMO/images/lalrq0mi_xys1xwo.jpeg",
"size": 40000,
"width": 200,
"height": 200,
"file_name": "test_filename"
}
}
Sponsored Brands Image Asset Uploading Methods
We provide two ways to upload image assets for Sponsored Brands:
- Option 1: Upload the file using Moloco’s CDN solution
- Option 2: Upload by CDN URL using your own CDN solution.
Before creating a Sponsored Brands campaign you must upload the image(s) which are used for the banner (image_asset_type:BANNER
) or logo (image_asset_type:LOGO
).
Use
multipart/form-data
Content-type to support sending both File and JSON when making [CreateImageAsset] API requests. Do not useapplication/json
Supported image formats
Image Format | Default Maximum File Size |
---|---|
JPG/JPEG, PNG, WEBP | Configurable at platform level |
GIF | Configurable at platform level |
Option 1: Upload by File
There are two keys named file
, and image_asset
-
The file must be uploaded in the key named file. If the key file is not used, the request will fail to parse the upload properly.
-
The image asset’s metadata must be included as a json value in the key named
image_asset
. There are additional fields for the request, such asad_account_id
,title
, andimage_asset_type
See the CreateImageAsset API reference for more details.
Option 2: Upload by CDN URL
When using your own CDN solution, use only the image_asset
key with JSON format.
Use only one option when uploading creatives: either
file
orimage_asset.image_url
(JSON content). These methods cannot be used together in the same request.
Sponsored Brands campaign review
By default your platform is configured to use an image asset and landing page review process. This process requires all assets and landing pages to be approved by the platform owner before a campaign can serve ads. You may disable the asset and/or landing page review systems, when disabled all assets and landing pages are auto-approved enabling campaigns to serve ads without any intervention.
- Campaigns require a minimum of at least one
Active
asset and one landing page to activate. All assets and landing pages used in the campaign must be in theApproved
andActive
state in order to launch the ad campaign and serve ads. (See Campaign States for more information.) - By default the review status for each new asset will be set to the state
IN_REVIEW
. The asset(s) review status can be changed by approving or rejecting the asset. You may approve or reject an individual or group of assets and/or the landing page(s) of the campaign and leave comments using the Campaign Review APIs. - Please refer to the UpdateCampaignReviewsBulkRequest API reference for more information on how to update multiple asset and landing page reviews within one request.
Campaign Management
There are 2 fields labeled assets
and landing_pages
within each campaign, both fields are an array, these fields are used for managing Sponsored Brands Campaigns.
When making a Decision API request only the latest approved asset group or landing page will be used.
Assets
All asset information for Sponsored Brand campaigns should be stored in the assets field.
A campaign’s assets must include all existing asset dimensions (pixel size). For example, if there are 2 inventories, 1 inventory with 400x200 banners and 1 inventory with 400x400 banners, the campaign should contain assets with image dimensions of 400x200 and 400x400.
Assets may have up to 4 elements:
- Banner
- Logo
- Headline
- Call-to-Action (CTA)
Asset features are configurable at the platform level, platform owners may set any element to required or optional. Please reach out to your Moloco representatives for more information regarding configuration options.
When creating a new asset or landing page, the fields id
, created_at
, and updated_at
must be empty. To update an asset or landing page, use the ReadImageAsset API to collect the latest information for the asset, then use the collected data with the UpdateCampaign API to update the asset.
Note: Approved assets are immutable. The latest approved asset(s) will always be used when a Decision request is made.
Asset Validation
Exact Match
By default, when uploading an asset, such as a banner image, the exact dimensions set from the inventory (i.e. 400x400 pixels) is required and validated. All dimension group assets marked as required by the platform owner such as Banner, Logo, Headline, and Call-to-Action (CTA) must be included.
Aspect Ratio Validation
To accept a range of image sizes platform owners may set the aspect ratio, minimum width, and minimum height instead of a static pixel size. Using this option requires populating the target_inventory_dimension
field inside the banner object. This field sets the dimensions that the asset should target; the aspect ratio should align with the actual width and height of the image. Only the Banner and Headline are required when using Aspect Ratio validation.
Example using Exact Match
{
"campaign": {
...
"ad_type": "BRAND",
"assets": [
{
"id": "asset-400x200", // should be empty for create request
"banner": { // Banner
"creative_id": "banner_image_asset_1", // image_asset_id for BANNER
"image_url": "https://moloco.com/400x200.png",
"width": 400,
"height": 200,
},
"logo": { // Brand Logo
"creative_id": "logo_image_asset_1", // image_asset_id for LOGO
"image_url": "https://moloco.com/logo.png"
},
"headline": { // headline
"text": "headline"
},
"cta": { // call-to-action
"text": "Click here"
},
"created_at": "time", // read-only
"updated_at": "time", // read-only
},
{
"id": "asset-400x400",
"banner": { // Banner
"creative_id": "banner_image_asset_2",
"image_url": "https://moloco.com/400x400.png",
"width": 400,
"height": 400,
},
"logo": {
"creative_id": "logo_image_asset_2", // image_asset_id for LOGO
"image_url": "https://moloco.com/logo.png"
},
"headline": { // headline
"text": "headline2"
},
"cta": { // call-to-action
"text": "Buy Now"
},
"created_at": "time", // read-only
"updated_at": "time", // read-only
}
},
...
}
Example using Aspect Ratio validation
{
"campaign": {
...
"ad_type": "BRAND",
"assets": [
{
"id": "asset-400x200",
"banner": { // Banner
"creative_id": "banner_image_asset_1", // image_asset_id for BANNER
"image_url": "https://moloco.com/400x200.png",
"width": 200,
"height": 100,
"target_inventory_dimension": {
"width": 400,
"height": 200
},
},
"headline": { // headline
"text": "headline"
},
"created_at": "time", // read-only
"updated_at": "time", // read-only
},
{
"id": "asset-400x400",
"banner": { // Banner
"creative_id": "banner_image_asset_2",
"image_url": "https://moloco.com/400x400.png",
"width": 400,
"height": 400,
"target_inventory_dimension": {
"width": 400,
"height": 400
},
},
"headline": { // headline
"text": "headline2"
},
"created_at": "time", // read-only
"updated_at": "time", // read-only
}
},
...
}
Landing Pages
The landing_pages
field in the campaign specifies which page the shopper will be redirected to after clicking the asset. There are 3 options:
- Custom URL - Specify a custom URL
- Product Detail Page (PDP) - Choose to redirect the shopper to specific item page
- Product List Page (PLP) - A page listing items in the Sponsored Brands campaign. When making a call to the Decision API the item list is provided in the response body
Although the landing_pages
field can store multiple landing pages, only the latest approved landing page will be used when a decision request is made, approved landing pages are immutable.
Option 1. Custom URL
Enter any valid URL for the landing page.
{
"id": "landing_page_custom_url",
"type": "CUSTOM_URL",
"custom_url_seting": {
"url": "https://moloco.com" // URL to be redirected
},
"created_at": "time", // read-only
"updated_at": "time", // read-only
}
Option 2. Product Detail Page
When redirecting to a specific product page, you must set the id
for the item. Each item in your catalog feed has an associated id
.
{
"id": "landing_page_pdp",
"type": "PRODUCT_DETAIL",
"product_detail_setting": {
"item_id": "catalog_item_id" // Catalog Item ID to be redirected
},
"created_at": "time", // read-only
"updated_at": "time", // read-only
}
Option 3. Product List Page
Redirecting to list of products in the campaign. The Product List is provided within the Decision API response, no additional settings required.
{
"id": "landing_page_plp",
"type": "PRODUCT_LIST",
"product_list_setting": {
// Nothing to set.
},
"created_at": "time", // read-only
"updated_at": "time", // read-only
}
Decision API Requests
Once a campaign is Active
it may serve ads, please refer to the Decision API reference to for more information on making decision requests for Sponsored Products, Sponsored Banner and Sponsored Brands campaigns.
Calling DecideAdBrands tracker URLs
For a Sponsored Brands, when a campaign is selected by auction, the impressions, clicks, assets, and the items for advertising are tracked independently.
When an impression or click occurs you must call the impression tracking URLs
and the click tracking URLs
provided within the response for each item and asset.
Note: The assets in a DecideAdBrands response are the property of the selected campaign. Both the items and image assets in the response are tracked independently.
Example DecideAdBrands Response body:
{
"request_id": "brand_request",
"decisions": [
{
"inventory_id": "INVENTORY_ID",
"ads": [
{
"auction_result": {
"ad_account_id": "AD_ACCOUNT_ID",
"campaign_id": "CAMPAIGN_ID",
"win_price": {
"currency": "USD",
"amount_micro": "2100000"
}
},
"asset": {
"id": "ASSET_ID",
"banner": {
"image_url": "ASSET_IMAGE_URL"
},
"logo": {
"image_url": "LOGO_IMAGE_URL"
},
"headline": {
"text": "HEADLINE_TEXT"
},
"cta": {
"text": "CTA_TEXT"
},
"imp_trackers": [
"ASSET_IMP_TRACKER_URL"
],
"click_trackers": [
"ASSET_CLICK_TRACKER_URL"
]
},
"landing_page": {
"type": "CUSTOM_URL",
"custom_url_setting": {
"url": "https://moloco.com"
}
},
"items": [
{
"item_id": "1",
"imp_trackers": [
"ITEM_1_IMP_TRACKER_URL"
],
"click_trackers": [
"ITEM_1_CLICK_TRACKER_URL"
]
},
{
"item_id": "1044",
"imp_trackers": [
"ITEM_2_IMP_TRACKER_URL"
],
"click_trackers": [
"ITEM_2_CLICK_TRACKER_URL"
]
}
]
}
]
}
]
}
Updated 2 days ago