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

Adjustable Features

Uploading Image Assets

Sponsored Brands and Sponsored Display 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.

{
  "ad_account_id": "ad account",
  "title": "asset title",
  "type": "IMAGE",
  "image_source": {
    "url": "https://cnd.com/platform/images/test.jpeg",
    "size": 40000,
    "width": 200,
    "height": 200,
    "file_name": "test" 
  }

Uploading Methods

Before creating a Sponsored Brands or Sponsored Display campaign you must upload the image(s) which are used for the banner (image_asset_type:BANNER) or logo (image_asset_type:LOGO).

When creating a new asset or landing page, the fields id, created_at, and updated_at must be left 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.

🚧

• Use multipart/form-data Content-type to support sending both File and JSON when making CreateImageAsset API requests. Do not use application/json
• When uploading creatives: use either file or image_asset.image_url (JSON content). These methods cannot be combined together in the same request.

We provide 2 methods to upload image assets for Sponsored Brands and Sponsored Display:

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 the Approved and Active 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 and Sponsored Display Campaigns.

🚧

Approved assets are immutable. 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 both image dimensions of 400x200 and 400x400.

Assets may have up to 4 elements:

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.

Example:

{
"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
    }
},
...

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:

  {
  "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 for Sponsored Brands and 2 options for Sponsored Display:

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 Brands, and Sponsored Display 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 in the response.

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.

Example:

{
  "request_id": "ABCD1234",
  "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": "CUSTOM_URL"
            }
          },
           "product_detail_setting": {
            "item_id": "string"
          },
         ....

Calling DecideAdDisplay Tracker URLs

For a Sponsored Display, when a campaign is selected by auction, the impressions, clicks, and assets for advertising are tracked independently in the response.

When an impression or click occurs you must call the impression tracking URLs and the click tracking URLs provided within the response for each asset.

Example:

{
  "request_id": "ABCD1234",
  "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",