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 the System 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.

Image Format	Default Maximum File Size
JPG/JPEG, PNG, WEBP	1MB / 1024KB
GIF	3MB / 3072KB

Image Format	Default Maximum File Size
JPG/JPEG, PNG, WEBP	Configurable at platform level
GIF	Configurable at platform level

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"
              ]
            }
          ]
        }
      ]
    }
  ]
}