Ad Unit Management API

Ad Unit Management API에 요청을 전송하여 MAX 광고 단위를 조회하고 관리할 수 있습니다.

이 API에는 다섯 개의 엔드포인트가 있습니다.

1. /ad_unit 엔드포인트:
   • 특정 광고 단위에 대한 세부 정보를 보려면 /ad_unit/«ad-unit-ID»로 GET 요청을 보냅니다.
   • 새로운 광고 단위를 생성하려면 /ad_unit/로 POST 요청을 보냅니다.
   • 광고 단위의 ad network 설정을 관리하려면 /ad_unit/«ad-unit-ID»로 POST 요청을 보냅니다.
   • 광고 단위의 segment에 대한 waterfall을 가져오려면 /ad_unit/«ad-unit-ID»/«segment-ID»로 GET 요청을 보냅니다.
   • 광고 단위의 segment에 대한 waterfall을 생성, 수정, deprecate, promote 또는 제거하려면 /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 요청을 보냅니다.
   • 광고 단위 실험을 promote하거나 deprecate하려면 /ad_unit_experiment/«ad-unit-ID»로 POST 요청을 보냅니다.
   • 광고 단위 실험의 segment에 대한 waterfall을 가져오려면 /ad_unit_experiment/«ad-unit-ID»/«segment_id»로 GET 요청을 보냅니다.
   • 광고 단위 실험의 segment에 대한 waterfall을 생성, 수정, deprecate, promote 또는 제거하려면 /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)하려면 이 엔드포인트를 사용하십시오. (광고 단위 실험을 생성, 업데이트, promote 또는 비활성화하려면 아래에 설명된 /ad_unit_experiment/ 엔드포인트를 참조하십시오.) MAX는 여기서 설정한 CPM 값을 사용하여 waterfall을 정의합니다. 계정 및 특정 ad network가 Auto-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 배열에는 설정된 ad network당 하나의 Ad Network Object가 포함됩니다. Network API Name(예: FACEBOOK_NETWORK)은 각 Ad Network Object의 키입니다. 각 ad network는 특정 필드를 요구합니다. 이러한 필드의 의미를 알아보려면 아래의 ad network object 표 및 그 뒤에 나오는 표들을 참조하십시오. Network API Name 객체 키 및 특정 필드를 설정하는 방법에 대한 네트워크별 지침은 ad networks 표를 참조하십시오.

ad network object

ad_network_ad_units 객체

특정 ad network에 적용한 변경 사항은 다른 ad networks의 설정에 영향을 미치지 않습니다. 하나의 ad network만 업데이트하는 경우 모든 ad networks를 포함하는 요청을 보낼 필요는 없습니다. 특정 ad network 설정의 일부를 변경하려면 해당 ad network에 대한 MAX 광고 단위와 관련된 모든 정보를 포함해야 합니다. 기존 ad network에 새로운 광고 단위를 추가하려면 해당 ad network에 대한 다른 모든 광고 단위를 요청에 포함하십시오. ad network에 대해 모든 광고 단위들을 disabled로 표시하면 해당 ad network가 비활성화됩니다.

countries 객체

이 객체는 ad_network_ad_unit에서 어떤 국가가 포함되거나 제외되는지 정의합니다.

frequency_capping_settings 객체

frequency cap의 두 가지 스타일은 session 기반과 time 기반입니다. session 기반 frequency caps의 경우, 각 사용자는 session에서 최대 해당 횟수만큼의 광고를 보게 됩니다. time 기반 caps의 경우, 사용자는 설정된 시간 프레임(분 단위로 정의) 내에 설정된 횟수의 광고를 보게 됩니다.

bid_floors 객체

이 객체는 특정 국가와 연결하려는 CPM bid floors를 정의합니다. bid floors를 정의하지 않은 국가는 floor가 적용되지 않습니다. bid_floors 객체를 포함하는 모든 업데이트 요청에는 floors의 전체 목록을 포함하십시오.

banner_refresh_settings 객체

이 객체는 banner 광고 단위들이 새로고침되고 새로운 banner 광고를 가져와야 하는 주기를 정의합니다. interval을 0으로 설정하면, 이 광고 단위는 MAX가 정의한 기본 새로고침 주기로 새로고침됩니다.

mrec_refresh_settings 객체

이 객체는 MREC 광고 단위들이 새로고침되고 새로운 MREC 광고를 가져와야 하는 주기를 정의합니다. interval을 0으로 설정하면, 이 광고 단위는 MAX가 정의한 기본 새로고침 주기로 새로고침됩니다.

segment 객체

이 객체는 인벤토리의 서로 다른 segments에 대해 서로 다른 광고 단위 waterfall들을 생성하는 사용자 segmentation 타겟팅 규칙을 정의합니다. ID 상태 및 디바이스 유형별로 사용자 segmentation을 수행할 수 있습니다. 자세한 내용은 SDK 연동 가이드 > Platform > 개요 > 데이터 및 키워드 전달 문서를 참조하십시오.

메인 광고 단위에서 segment 객체들은 segments(복수형)라는 목록에 포함되어 있습니다. 이는 해당 광고 단위와 연결된 waterfall segmentation의 읽기 전용 목록입니다. segmentation이 정의된 특정 광고 단위 waterfall을 조회하거나 새로운 waterfall을 생성할 때, segment 객체는 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» 엔드포인트

광고 단위 실험을 생성, 조회, 수정, promote 또는 deprecate하려면 이 엔드포인트를 사용하십시오. 모든 광고 단위 실험에 대한 더 자세한 정보를 보려면 요청에 쿼리 매개변수 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":[{…}], // 상위 광고 단위와 동일
  "frequency_capping_settings": […],
  "bid_floors":[{…}] // 상위 광고 단위와 동일
}

실험 deprecate 요청 본문

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

실험 deprecate 응답 본문

{
  "message": "Experiment successfully deprecated"
}

실험 promote 요청 본문

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

실험 promote 응답 본문

{
  "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 엔드포인트에서 반환하는 객체들과 동일합니다.

다중 waterfalls

사용자 segmentation을 기반으로 광고 단위에 대한 추가 waterfalls를 생성할 수 있습니다. 이 페이지에 설명된 다른 요청들과 유사한 구조를 사용하여 waterfalls를 생성 및 수정하고, waterfall experiments를 생성/수정/deprecate/promote할 수 있습니다. 요청을 적용하려는 segment를 지정하려면 엔드포인트 끝에 /«segment-ID»를 추가하십시오. 여기서 «segment-ID»는 광고 단위 응답의 segment 객체에 있는 id 값입니다. 새로운 segments는 광고 단위에 설정된 기본 waterfall과 동일한 waterfall로 시작합니다. 사용자 segmentation을 정의하는 방법에 대한 자세한 내용은 segment 객체를 참조하십시오.

예시

GET

광고 단위 1234567890abcdef의 segment ID 213에 대한 waterfall 가져오기:

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

광고 단위 1234567890abcdef의 segment ID 213에 대한 experiment waterfall 가져오기:

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

POST

광고 단위 1234567890abcdef의 No-ID iPhone 사용자를 위한 새로운 waterfall 생성하기:

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에 대한 waterfall 제거하기 (disabled를 true로 설정):

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
}

Ad networks

이 표는 Ad Unit API가 ad network 및 앱 식별자에 사용하는 이름과 각 ad network에서 사용되는 이름 간의 매핑을 제공합니다. 네트워크에 여기에 나열된 ad_network_app_id (ID) 또는 ad_network_app_key (Key) 값이 있는 경우, ad_network_settings 객체를 업데이트하는 요청을 보낼 때 해당 값이 필수적으로 요구됩니다. 네트워크에 해당 필드에 대해 여기에 나열된 값이 없는 경우, 값은 요구되지 않습니다.

¹ Mintegral Bidding은 다른 Placement ID를 포함할 수 있습니다. API는 최상위 객체의 extraParameters라는 객체에서 이를 처리합니다. extraParameters 객체에는 이 Placement ID 값을 받는 ad_network_optional_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"
    }
  }
}