Ad Unit Management API

您可以向 Ad Unit Management API 发送请求，来查看和管理 MAX 广告单元。

该 API 有 5 个终端：

1. /ad_unit 终端：
   • 向 /ad_unit/«ad-unit-ID» 发送 GET 请求，以查看特定广告单元的详细信息。
   • 向 /ad_unit/ 发送 POST 请求，以创建新的广告单元。
   • 向 /ad_unit/«ad-unit-ID» 发送 POST 请求，以管理广告单元的广告平台配置。
   • 向 /ad_unit/«ad-unit-ID»/«segment-ID» 发送 GET 请求，以获取广告单元的用户分群瀑布流。
   • 向 /ad_unit/«ad-unit-ID»/«segment-ID» 发送 POST 请求，以创建、编辑、弃用、采纳或移除广告单元的用户分群瀑布流。
2. /ad_units 终端
   • 向 /ad_units 发送 GET 请求，以查看所有广告单元的详细信息。
3. /ad_unit_experiment 终端
   • 向 /ad_unit_experiment/«ad-unit-ID» 发送 GET 请求，以查看广告单元实验的详细信息。
   • 如果该广告单元当前没有正在运行的实验，向 /ad_unit_experiment/«ad-unit-ID» 发送 POST 请求，以创建新的广告单元实验。
   • 向 /ad_unit_experiment/«ad-unit-ID» 发送 POST 请求，以采纳或弃用广告单元实验。
   • 向 /ad_unit_experiment/«ad-unit-ID»/«segment_id» 发送 GET 请求，以获取广告单元实验的用户分群瀑布流。
   • 向 /ad_unit_experiment/«ad-unit-ID»/«segment_id» 发送 POST 请求，以创建、编辑、弃用、采纳或移除广告单元实验的用户分群瀑布流。
4. /test_device 终端
   • 向 /test_device 发送 POST 请求，以创建新的测试设备。
   • 向 /test_device/«test-device-ID» 发送 GET 请求，以查看特定测试设备的详细信息。
   • 向 /test_device/«test-device-ID» 发送 POST 请求，以管理测试设备的配置。
5. /test_devices 终端
   • 向 /test_devices 发送 GET 请求，以查看所有测试设备的详细信息。

下方版块将更详细地阐释这些终端。

/ad_unit 终端

要创建广告单元，请向此终端发送 POST 请求。请在请求体中添加下方所述的必填字段。每个请求只能创建一个广告单元。

目标 URL

https://o.applovin.com/mediation/v1/ad_unit

POST

请求体

{
  "name": "My Inter Ad Unit",
  "platform": "ios",
  "package_name": "com.test.app",
  "ad_format": "INTER"
}

响应体

{
  "id": "1234567890abcdef",
  "name": "My Inter Ad Unit",
  "platform": "ios",
  "package_name": "com.test.app",
  "ad_format": "INTER",
  "has_active_experiment": false,
  "disabled": false
}

请求/响应体字段对照表

/ad_unit/«ad-unit-ID» 终端

使用此终端查看 (GET) 或编辑 (POST) 广告单元配置。(要创建、更新、采纳或禁用广告单元实验，请参阅下文所述的 /ad_unit_experiment/ 终端。MAX 会使用您在此处设置的 CPM 值来定义瀑布流。但是，如果您为账户和特定广告平台配置为启用 Auto CPM，那么此处设置的值就是默认 CPM 值。Auto CPM 接收到新值后，该默认 CPM 值就不再适用。

要更详细地查看广告单元，请添加查询参数 fields。将该参数的值设置为以逗号分隔的值列表，列出您要查看的所有其他字段的名称。可能的 fields 包括：ad_network_settings (仅限激活状态)，disabled_ad_network_settings (仅限禁用状态)，frequency_capping_settings，bid_floors，segments，banner_refresh_settings 和 mrec_refresh_settings。请参阅下文说明，了解与这些 fields 值对应的对象。

目标 URL

https://o.applovin.com/mediation/v1/ad_unit/«ad-unit-ID»?fields=ad_network_settings,disabled_ad_network_settings,frequency_capping_settings,bid_floors,banner_refresh_settings,segments

示例

GET

响应体

{
  "id": "1234567890abcdef",
  "name": "My Inter Ad Unit",
  "platform": "ios",
  "package_name": "com.test.app",
  "ad_format": "INTER",
  "has_active_experiment": false,
  "disabled": false,
  "ad_network_settings": [
    {
      "FACEBOOK_NETWORK": {
        "disabled": false,
        "ad_network_ad_units": [
           {
             "ad_network_ad_unit_id": "8247030622430922_5618972399256249",
             "disabled": false
           }
        ]
      }
    },
    {
      "ADMOB_NETWORK": {
        "disabled": false,
        "ad_network_app_id": "ca-app-pub-3555987499620362~3024971981",
        "ad_network_ad_units": [
          {
            "ad_network_ad_unit_id": "ca-app-pub-3555987499620362/4382996128",
            "disabled": false,
            "cpm": "30.00",
            "countries": {
              "type": "INCLUDE",
              "values": [
                "us",
                "ca",
                "gb",
                "au"
              ]
            }
          },
          {
            "ad_network_ad_unit_id": "ca-app-pub-3555987499620362/5476585941",
            "disabled": false,
            "cpm": "20.00",
            "countries": {
              "type": "EXCLUDE",
              "values": [
                "us",
                "ca",
                "gb",
                "au"
              ]
            }
          }
        ]
      }
    }
  ],
  "frequency_capping_settings": [
    {
      "type": "time",
      "time_capping_settings": {
        "day_limit": 10,
        "minute_frequency": 10
      },
      "session_capping_settings": {
        "session_limit": 0
      },
      "countries" : {
        "type": "INCLUDE",
        "values" : [
          "ca",
          "us"
        ]
      }
    }
  ],
  "bid_floors": [
    {
      "country_group_name": "t1 eng",
      "cpm": "10.00",
      "countries": {
        "type": "INCLUDE",
        "values": [
          "au",
          "ca",
          "gb",
          "nz",
          "us"
        ]
      }
    },
    {
      "country_group_name": "eea",
      "cpm": "5.00",
      "countries": {
        "type": "INCLUDE",
        "values": [
          "at",
          "pt",
          "ro",
          "se",
          "si",
          "sk"
        ]
      }
    }
  ],
  "banner_refresh_settings":{
    "interval": 0
  },
  "segments":[
    {
      "id": 347324,
      "name": "LAT iPads",
      "id_type": "no_id",
      "device_type": "tablets",
      "segment_keys": [
        [
          "+1:2"
        ]
      ]
    }
  ]
}

POST

请求体

{
  "id":"«ad-unit-ID»",
  "name":"«ad-unit-name»",
  "platform":"«ad-unit-platform»",
  "ad_format":"«ad-unit-format»",
  "package_name":"«ad-unit-package-name»",
  "ad_network_settings": [
    {
      "ADMOB_NETWORK": {
        "disabled": true,
        "ad_network_app_id": "ca-app-pub-3555987499620362~3024971981",
        "ad_network_ad_units": []
      }
    }
  ],
  "frequency_capping_settings": [
    {
      "type": "time",
      "time_capping_settings": {
        "day_limit": 10,
        "minute_frequency": 10
      },
      "session_capping_settings": {
        "session_limit": 0
      },
      "countries" : {
        "type": "INCLUDE",
        "values" : [
          "ca",
          "us"
        ]
      }
    }
  ]
}

响应

响应中返回所有广告单元的详细信息。

ad_network_settings 数组

每个已配置的广告平台ad_network_settings 数组都包含 1 个广告平台对象。每个广告平台对象的键是该平台 API 名称 (例如 FACEBOOK_NETWORK)。每个广告平台都有特定的必要字段。请参阅下方的广告平台对象对照表及其之后的表格，了解这些字段的含义。要了解如何设置平台 API 名称对象键和部分字段，请参阅广告平台表格。

广告平台对象

ad_network_ad_units 对象

您对特定广告平台所做的变更不会影响其他广告平台的配置。如果您只更新其中一个广告平台，则无需发送包含全部广告平台的请求。要更改特定广告平台配置的一部分，您必须为该广告平台添加与 MAX 广告单元相关的全部信息。如需向现有广告平台添加新的广告单元，请在请求中包含该广告平台的全部其他广告单元。如果将某个广告平台的全部广告单元标记为 disabled，则会禁用该广告平台。

countries 对象

该对象说明指定 ad_network_ad_unit 中包含或排除的国家/地区。

frequency_capping_settings 对象

频率上限分为两种，一种基于会话，另一种基于时间。基于会话的频率上限，是指每位用户最多能在一个会话中看到多少个广告。基于时间的频率上限，则指用户在指定时间范围内 (以分钟计) 能看到的广告数量。

bid_floors 对象

该对象定义您要与特定国家/地区相关联的任何 CPM 底价。未定义底价的国家/地区将没有竞价下限。如果您的更新请求包含 bid_floors 对象，那么请在请求中加入最低限价的完整列表。

banner_refresh_settings 对象

该对象定义了横幅广告单元刷新时间间隔，以及调取新横幅广告的频率。如果您将 interval 设置为 0，那么该广告单元将以 MAX 指定的默认频率刷新。

mrec_refresh_settings 对象

该对象定义了 MREC 广告单元刷新时间间隔，以及调取新 MREC 广告的频率。如果您将 interval 设置为 0，那么该广告单元将以 MAX 指定的默认频率刷新。

segment 对象

该对象定义用户分群定向规则，为不同库存部分创建不同的广告单元瀑布流。您可以按照 ID 状态和设备类型进行用户分群。请查看 SDK 集成指南 > 平台 > 概述 > 数据和关键词传递文档了解更多信息。

在主广告单元上，segment 对象包含在名为 segments (复数) 的列表中。该瀑布流细分为只读列表，仅与该广告单元关联。查看指定了细分的广告单元瀑布流或创建新瀑布流时，细分对象就会与 segment 键 (单数) 相关联。

可能出现的错误

/ad_units 终端

使用此终端查看所有活跃广告单元的基本详情。向此终端发送的 GET 请求仅会返回活跃的广告单元。您无法通过该 API 禁用或激活广告单元。要禁用或激活广告单元，请在 UI 中进行设置。

在请求中包含查询参数 fields，您就能获得所有活跃广告单元的详细信息。将该参数的值设置为以逗号分隔的值列表，列出您要查看的所有其他字段的名称。可能的 fields 包括 ad_network_settings，frequency_capping_settings 和 bid_floors。如同您使用 /ad_unit/«ad-unit-ID» 终端 请求单一广告单元，会自动返回对应对象一样——您在请求额外的字段时，返回的字段值就会与这些对应对象的值相同。

如果广告单元过多，您向该终端发送的请求可能会超时，或返回 500 响应代码。您可以添加查询参数 limit，限制返回的广告单元数量。将该值设置为整数，指示请求应返回的广告单元数量。要对所有广告单元分页查询，请添加查询参数 offset。将该值设置为整数，描述应当跳过总列表中的多少个广告单元，才会显示结果集中的首个结果。如果 offset 值大于广告单元总量，响应就会返回一个空数组。

目标 URL

https://o.applovin.com/mediation/v1/ad_units

示例

GET

响应体

[
  {
    "name": "My Inter Ad Unit",
    "platform": "ios",
    "package_name": "com.test.app",
    "ad_format": "INTER",
    "id": "45de6aa565cf865f",
    "has_active_experiment": false,
    "disabled": false
  },
  {
    "name": "My Rewarded Ad Unit",
    "platform": "android",
    "package_name": "com.test.app",
    "ad_format": "REWARD",
    "id": "565c45df8e6aa65f",
    "has_active_experiment": false,
    "disabled": false
  }
]

广告单元对象

可能出现的错误

/ad_unit_experiment/«ad-unit-ID» 终端

您可以使用此终端来创建、查看、编辑、采纳或弃用广告单元实验。要更详细地查看所有广告单元实验，请在请求中包含查询参数 fields。将该参数的值设置为以逗号分隔的字段名称列表，列出您要查看的值的字段名称。 可能的 fields 包括 ad_network_settings、frequency_capping_settings 和 bid_floors。请参阅上文，了解与这些 fields 值对应的对象。

目标 URL

https://o.applovin.com/mediation/v1/ad_unit_experiment/«ad-unit-ID»?fields=ad_network_settings,frequency_capping_settings,bid_floors

示例

GET

响应体

{
  "id": "e74c3b7797b0ce7a",
  "experiment_name": "add_admob_inter_lines",
  "platform": "ios",
  "ad_format": "INTER",
  "package_name": "com.testapp.test",
  "disabled": false,
  "promote": false,
  "deprecate": false,
  "ad_network_settings": [
    {
      "ADMOB_NETWORK": {
        "disabled": true,
        "ad_network_app_id": "ca-app-pub-3555987499620362~3024971981",
        "ad_network_ad_units": []
      }
    }
  ],
  "frequency_capping_settings": [
    {
      "type": "time",
      "time_capping_settings": {
        "day_limit": 10,
        "minute_frequency": 10
      },
      "session_capping_settings": {
        "session_limit": 0
      },
      "countries" : {
        "type": "INCLUDE",
        "values" : [
          "ca",
          "us"
        ]
      }
    }
  ],
  "bid_floors": [
    {
      "country_group_name": "t1 eng",
      "cpm": "10.00",
      "countries": {
        "type": "INCLUDE",
        "values": [
          "au",
          "ca"
        ]
      }
    }
  ]
}

POST

创建实验请求体

向该终端发送实验创建请求时，请在请求体中排除 id 值，或将该值设置为 null。

{
  "experiment_name": "test_adjusting_frequency_cap",
  "frequency_capping_settings": […]
}

创建实验响应体

{
  "id": "e74c3b7797b0ce7a",
  "experiment_name": "test_adjusting_frequency_cap",
  "disabled": false,
  "promote": false,
  "deprecate": false,
  "ad_network_settings":[{…}], // same as parent ad unit
  "frequency_capping_settings": […],
  "bid_floors":[{…}] // same as parent ad unit
}

弃用实验请求体

{
  "id": "e74c3b7797b0ce7a",
  "experiment_name": "test_adjusting_frequency_cap",
  "promote": false,
  "deprecate": true
}

弃用实验响应体

{
  "message": "Experiment successfully deprecated"
}

采纳实验请求体

{
  "id": "e74c3b7797b0ce7a",
  "experiment_name": "test_adjusting_frequency_cap",
  "promote": true,
  "deprecate": false
}

采纳实验响应体

{
  "message": "Experiment successfully promoted"
}

广告单元实验对象

可能出现的错误

/test_device 终端

要创建测试设备，请向此终端发送 POST 请求。请在请求体中添加下方所述的必填字段。每个请求只能创建一个测试设备。

目标 URL

https://o.applovin.com/mediation/v1/test_device

示例

请求体

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": false,
  "network": "APPLOVIN_NETWORK"
}

响应体

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": false,
  "network": "APPLOVIN_NETWORK"
}

请求/响应体字段对照表

/test_device/«test-device-ID» 终端

使用此终端查看 (GET) 或编辑 (POST) 测试设备配置。

目标 URL

https://o.applovin.com/mediation/v1/test_device/«test-device-ID»

示例

目标 URL

https://o.applovin.com/mediation/v1/test_device/2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1

GET

响应体

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": false,
  "network": "APPLOVIN_NETWORK"
}

POST

请求体

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": true,
  "network": "FACEBOOK_NETWORK"
}

响应体

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": true,
  "network": "FACEBOOK_NETWORK"
}

该 JSON 对象与 /test_device 终端 返回的对象相同。

/test_devices 终端

使用此终端查看您的账户中所有测试设备的基本详情。响应中同时包含已禁用和启用的测试设备。

目标 URL

https://o.applovin.com/mediation/v1/test_devices

示例

响应体

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": false,
  "network": "APPLOVIN_NETWORK"
},
{
  "name": "My Test Device 2",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe2",
  "disabled": false,
  "network": "FACEBOOK_NETWORK"
}

这些 JSON 对象与 /test_device 终端 返回的对象相同。

多瀑布流

您可以基于用户分群，为指定广告单元创建额外的瀑布流。您可以使用与本页中其他请求类似的结构，创建或编辑瀑布流，或创建/编辑/弃用/采用瀑布流实验。要指定应用请求的用户分群，请在终端末尾附加 /«segment-ID»，其中 «segment-ID» 为广告单元响应中来自 segment 对象的 id 值。新分群的初始瀑布流与广告单元默认配置的瀑布流相同。请参阅 segment 对象，进一步了解如何定义用户分群。

示例

GET

获取广告单元 1234567890abcdef 中 segment ID 213 的瀑布流：

https://o.applovin.com/mediation/v1/ad_unit/1234567890abcdef/213

获取广告单元 1234567890abcdef 中 segment ID 213 的实验瀑布流：

https://o.applovin.com/mediation/v1/ad_unit_experiment/1234567890abcdef/213

POST

为广告单元 1234567890abcdef 中 No-ID iPhone 用户创建新瀑布流：

https://o.applovin.com/mediation/v1/ad_unit/1234567890abcdef

{
  "id": "1234567890abcdef", // ad unit ID
  "name": "MyApp_iOS_Banners", // ad unit name
  "platform": "ios",
  "ad_format": "BANNER",
  "package_name": "com.company.myapp",
  "disabled": false,
  "segment": {
    "name": "No-ID iPhones", // waterfall name
    "id_type": "no_id",
    "device_type": "phones",
    "segment_keys": [
      [
        "+1:2"
      ]
    ]
  }
}

移除广告单元 1234567890abcdef 中 segment ID 213 的瀑布流 (将 disabled 设为 是)：

https://o.applovin.com/mediation/v1/ad_unit/1234567890abcdef/213

{
  "id": "1234567890abcdef", // ad unit ID
  "name": "MyApp_iOS_Banners", // ad unit name
  "platform": "ios",
  "ad_format": "BANNER",
  "package_name": "com.company.myapp",
  "disabled": true
}

广告平台

参考该表格，了解广告单元 API 用于广告平台和应用标识符的名称，与各广告平台内部名称之间的对应关系。如果此处列出的广告平台具有 ad_network_app_id (ID) 或 ad_network_app_key (Key) 值，那么在发送 ad_network_settings 对象更新请求时，就必须提供该值。如果表格中并未列出平台相应字段的值，则无需提供。

¹ Mintegral Bidding 可以添加一个额外的 Placement ID。该 ID 会在 API 中通过调用顶层对象中的 extraParameters 对象进行处理。extraParameters 对象有名为 ad_network_optional_placement_id 的字段，该字段会采用此 Placement ID 值。请参阅下方示例：

{
  "MINTEGRAL_BIDDING": {
    "disabled": false,
    "targets": {},
    "ad_network_ad_units": [
      {
        "ad_network_ad_unit_id": "1232524",
        "extraParameters": null,
        "disabled": false,
        "cpm": "1.23",
        "countries": {
          "type": "INCLUDE",
          "values": []
        }
      }
    ],
    "ad_network_app_id": "testappId",
    "ad_network_app_key": "testappKey",
    "extraParameters": {
      "ad_network_optional_placement_id": "1234354"
    }
  }
}