Работа с таргетингами (фокусировками)
Для выделения аудитории в сети Интернет традиционно используются механизмы таргетингов или фокусировок, позволяющие произвести выбор целевой аудитории, например, по географическому положению, времени суток. Система AdRiver поддерживает использование многоступенчатой системы таргетинга. Ограничения могут задаваться на этапе выделения рекламных мест под проведение кампании, в сценариях показа баннеров и в самих баннерах.
Более подробную информацию о таргетингах (фокусировках) можно получить из документации.
1. Таргетинг по географическому положению (геотаргетинг)
Использование программного интерфейса позволяет осуществлять следующие операции с геотаргетингами (фокусировками) в системе AdRiver:
- просмотр всех существующих в системе геозон;
- просмотр списка настроенных геозон для сценария;
- изменение настроек геозон для сценария;
- удаление настроенного геотаргетинга.
1.1. Просмотр всех геозон системы
Нижеследующий запрос позволяет получить список всех геозон, определенных в системе AdRiver.
GET/targeting/geo/zones Content-Type:application/atom+xml X-Auth-UserID:174291 X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%3E
В ответ система возвращает полный список всех геозон системы в виде XML в формате Atom Syndication Format – объекта Atom Entry.
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-05T15:02:25+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Geo Zones Atom Entry</title>
<id>https://api.adriver.ru/targeting/geo/zones</id>
<content type="text/xml">
<geoTargeting xmlns="http://adriver.ru/ns/restapi/atom">
<zone id="0" name="Неопределенный регион"/>
<zone id="1" name="Республика Хакасия (Абакан)"/>
<zone id="2" name="Архангельская область (Архангельск)"/>
<zone id="3" name="Астраханская область (Астрахань)"/>
<zone id="4" name="Белгородская область (Белгород)"/>
<zone id="5" name="Амурская область (Благовещенск)"/>
<zone id="6" name="Алтайский край (Барнаул)"/>
<zone id="7" name="Брянская область (Брянск)"/>
<zone id="8" name="Республика Бурятия (Улан-Уде)"/>
<zone id="9" name="Волгоградская область (Волгоград)"/>
<zone id="10" name="Владимирская область (Владимир)"/>
<zone id="11" name="Вологодская область (Вологда)"/>
<zone id="12" name="Воронежская область (Воронеж)"/>
<zone id="13" name="Республика Дагестан (Махачкала)"/>
<zone id="14" name="Свердловская область (Екатеринбург)"/>
<zone id="15" name="Ивановская область (Иваново)"/>
<zone id="16" name="Республика Ингушетия (Магас)"/>
<zone id="17" name="Иркутская область (Иркутск)"/>
<zone id="18" name="Республика Марий Эл (Йошкар-Ола)"/>
<zone id="19" name="Кабардино-Балкарская Республика (Нальчик)"/>
<zone id="20" name="Калужская область (Калуга)"/>
<zone id="21" name="Республика Калмыкия (Элиста)"/>
<zone id="22" name="Тверская область (Тверь)"/>
<zone id="23" name="Кемеровская область (Кемерово)"/>
<zone id="24" name="Камчатская область (Петропавловск-Камчатский)"/>
<zone id="25" name="Калининградская область (Калининград)"/>
<zone id="26" name="Республика Коми (Сыктывкар)"/>
<zone id="27" name="Кавказские Минеральные Воды"/>
<zone id="28" name="Курганская область (Курган)"/>
<zone id="29" name="Краснодарский край (Краснодар)"/>
<zone id="30" name="Красноярский край (Красноярск)"/>
<zone id="31" name="Костромская область (Кострома)"/>
<zone id="32" name="Курская область (Курск)"/>
<zone id="33" name="Санкт-Петербург и Ленинградская область"/>
<zone id="34" name="Липецкая область (Липецк)"/>
<zone id="35" name="Республика Адыгея (Майкоп)"/>
<zone id="36" name="Магаданская область (Магадан)"/>
<zone id="37" name="Республика Мордовия (Саранск)"/>
<zone id="38" name="Москва и Московская область"/>
<zone id="39" name="Мурманская область (Мурманск)"/>
<zone id="40" name="Новосибирская область (Новосибирск)"/>
<zone id="41" name="Нижегородская область (Нижний Новгород)"/>
<zone id="42" name="Новгородская область (Великий Новгород)"/>
<zone id="43" name="Омская область (Омск)"/>
<zone id="44" name="Орловская область (Орел)"/>
<zone id="45" name="Оренбургская область (Оренбург)"/>
<zone id="46" name="Республика Северная Осетия - Алания (Владикавказ)"/>
<zone id="47" name="Севастополь и Республика Крым (Симферополь)"/>
<zone id="48" name="Пензенская область (Пенза)"/>
<zone id="49" name="Приморский край (Владивосток)"/>
<zone id="50" name="Пермский край (Пермь)"/>
<zone id="51" name="Псковская область (Псков)"/>
<zone id="52" name="Ростовская область (Ростов-на-Дону)"/>
<zone id="53" name="Рязанская область (Рязань)"/>
<zone id="54" name="Сахалинская область (Южно-Сахалинск)"/>
<zone id="56" name="Смоленская область (Смоленск)"/>
<zone id="57" name="Самарская область (Самара)"/>
<zone id="59" name="Саратовская область (Саратов)"/>
<zone id="60" name="Ставропольский край (Ставрополь) без К.М.В."/>
<zone id="61" name="Республика Татарстан (Казань)"/>
<zone id="62" name="Тамбовская область (Тамбов)"/>
<zone id="63" name="Томская область (Томск)"/>
<zone id="64" name="Республика Тыва (Кызыл)"/>
<zone id="65" name="Тульская область (Тула)"/>
<zone id="66" name="Тюменская область (Тюмень)"/>
<zone id="67" name="Удмуртская Республика (Ижевск)"/>
<zone id="68" name="Ульяновская область (Ульяновск)"/>
<zone id="70" name="Республика Башкортостан (Уфа)"/>
<zone id="71" name="Хабаровский край (Хабаровск)"/>
<zone id="73" name="Чеченская Республика (Грозный)"/>
<zone id="74" name="Читинская область (Чита)"/>
<zone id="75" name="Челябинская область (Челябинск)"/>
<zone id="76" name="Карачаево-Черкесская Республика (Черкесск)"/>
<zone id="77" name="Чувашская Республика - Чувашия (Чебоксары)"/>
<zone id="78" name="Чукотский автономный округ (Анадырь)"/>
<zone id="79" name="Республика Саха - Якутия (Якутск)"/>
<zone id="80" name="Ярославская область (Ярославль)"/>
<zone id="81" name="межрегиональные сети России"/>
<zone id="82" name="Кировская область (Киров)"/>
<zone id="83" name="Республика Алтай (Горно-Алтайск)"/>
<zone id="84" name="Республика Карелия (Петрозаводск)"/>
<zone id="85" name="Ханты-Мансийский автономный округ - Югра (Ханты-Мансийск)"/>
<zone id="86" name="Ямало-Ненецкий автономный округ (Салехард)"/>
<zone id="87" name="Еврейская автономная область (Биробиджан)"/>
<zone id="88" name="Ненецкий автономный округ (Нарьян-Мар)"/>
<zone id="100" name="межрегиональные сети Украины"/>
<zone id="101" name="межрегиональные сети Республики Беларусь"/>
<zone id="102" name="Казахстан"/>
<zone id="103" name="Таджикистан"/>
<zone id="104" name="Абхазия"/>
<zone id="105" name="Минская область (Минск)"/>
<zone id="106" name="Брестская область (Брест)"/>
<zone id="107" name="Витебская область (Витебск)"/>
<zone id="108" name="Гомельская область (Гомель)"/>
<zone id="109" name="Гродненская область (Гродно)"/>
<zone id="110" name="Киев и Киевская область (Киев)"/>
<zone id="111" name="Винницкая область (Винница)"/>
<zone id="112" name="Волынская область (Луцк)"/>
<zone id="113" name="Днепропетровская область (Днепропетровск)"/>
<zone id="114" name="Донецкая область (Донецк)"/>
<zone id="115" name="Житомирская область (Житомир)"/>
<zone id="116" name="Закарпатская область (Ужгород)"/>
<zone id="117" name="Запорожская область (Запорожье)"/>
<zone id="118" name="Ивано-Франковская область (Ивано-Франковск)"/>
<zone id="120" name="Кировоградская область (Кировоград)"/>
<zone id="121" name="Луганская область (Луганск)"/>
<zone id="122" name="Львовская область (Львов)"/>
<zone id="123" name="Николаевская область (Николаев)"/>
<zone id="124" name="Одесская область (Одесса)"/>
<zone id="125" name="Полтавская область (Полтава)"/>
<zone id="126" name="Ровенская область (Ровно)"/>
<zone id="127" name="Сумская область (Сумы)"/>
<zone id="128" name="Тернопольская область (Тернополь)"/>
<zone id="129" name="Харьковская область (Харьков)"/>
<zone id="130" name="Херсонская область (Херсон)"/>
<zone id="131" name="Хмельницкая область (Хмельницкий)"/>
<zone id="132" name="Черкасская область (Черкассы)"/>
<zone id="133" name="Черниговская область (Чернигов)"/>
<zone id="134" name="Черновицкая область (Черновцы)"/>
<zone id="135" name="Могилёвская область (Могилев)"/>
<zone id="150" name="межрегиональные сети США"/>
<zone id="151" name="межрегиональные сети Канады"/>
<zone id="152" name="Израиль"/>
<zone id="153" name="Латвия"/>
<zone id="154" name="Япония"/>
<zone id="155" name="Австралия и Океания"/>
<zone id="156" name="межрегиональные сети Германии"/>
<zone id="157" name="Великобритания"/>
<zone id="158" name="Нидерланды"/>
<zone id="159" name="Германия, Бавария"/>
<zone id="160" name="Италия"/>
<zone id="161" name="Франция"/>
<zone id="162" name="Австрия"/>
<zone id="163" name="Испания"/>
<zone id="164" name="Португалия"/>
<zone id="165" name="Греция"/>
<zone id="166" name="Турция"/>
<zone id="167" name="Германия, Баден-Вюртемберг"/>
<zone id="168" name="Германия, Берлин"/>
<zone id="169" name="Германия, Бранденбург"/>
<zone id="170" name="Южная и Латинская Америка"/>
<zone id="171" name="Остальные страны Европы"/>
<zone id="172" name="Объединенные Арабские Эмираты"/>
<zone id="173" name="Германия, Бремен"/>
<zone id="174" name="Германия, Гамбург"/>
<zone id="175" name="Германия, Гессен"/>
<zone id="176" name="Германия, Мекленбург-Передняя"/>
<zone id="177" name="Германия, Нижняя Саксония"/>
<zone id="178" name="Германия, Рейнланд-Пфальц"/>
<zone id="179" name="Германия, Саар"/>
<zone id="180" name="Германия, Саксония"/>
<zone id="181" name="Германия, Саксония-Ангальт"/>
<zone id="182" name="Германия, Северный Рейн-Вестфалия"/>
<zone id="183" name="Германия, Тюрингия"/>
<zone id="184" name="Германия, Шлезвиг-Гольштейн"/>
<zone id="201" name="Польша"/>
<zone id="203" name="Швеция"/>
<zone id="204" name="Остальные Азиатские страны"/>
<zone id="205" name="Африка"/>
<zone id="208" name="Канада, Альберта (AB)"/>
<zone id="211" name="США, Аляска (AK)"/>
<zone id="212" name="США, Арканзас (AR)"/>
<zone id="213" name="США, Аризона (AZ)"/>
<zone id="214" name="Канада, Британская Колумбия (BC)"/>
<zone id="216" name="США, Калифорния (CA)"/>
<zone id="220" name="США, Колорадо (CO)"/>
<zone id="221" name="США, Федеральный округ Колумбия (DС)"/>
<zone id="223" name="США, Делавэр (DE)"/>
<zone id="224" name="США, Флорида (FL)"/>
<zone id="226" name="США, Джорджия (GA)"/>
<zone id="228" name="США, Гавайи (HI)"/>
<zone id="229" name="США, Айова (IA)"/>
<zone id="230" name="США, Айдахо (ID)"/>
<zone id="231" name="США, Иллинойс (IL)"/>
<zone id="233" name="США, Индиана (IN)"/>
<zone id="234" name="США, Канзас (KS)"/>
<zone id="235" name="США, Кентукки (KY)"/>
<zone id="236" name="США, Луизиана (LA)"/>
<zone id="237" name="США, Массачусетс (MA)"/>
<zone id="239" name="Канада, Манитоба (MB)"/>
<zone id="241" name="США, Мэриленд"/>
<zone id="243" name="США, Мэн (ME)"/>
<zone id="244" name="США, Мичиган (MI)"/>
<zone id="246" name="США, Миннесота (MN)"/>
<zone id="248" name="США, Миссури (MO)"/>
<zone id="249" name="США, Миссисипи (MS)"/>
<zone id="251" name="США, Монтана (MT)"/>
<zone id="252" name="Канада, Нью-Брансуик (NB)"/>
<zone id="253" name="США, Северная Каролина (NC)"/>
<zone id="254" name="США, Северная Дакота (ND)"/>
<zone id="255" name="США, Небраска (NE)"/>
<zone id="256" name="Канада, Ньюфаундленд и Лабрадор (NF)"/>
<zone id="257" name="США, Нью-Хэмпшир"/>
<zone id="258" name="США, Нью-Джерси (NJ)"/>
<zone id="259" name="США, Нью-Мексико (NM)"/>
<zone id="260" name="Канада, Новая Шотландия (NS)"/>
<zone id="262" name="Канада, Северо-Западные территории (NT)"/>
<zone id="263" name="Канада, Нунавут (NU)"/>
<zone id="264" name="США, Невада (NV)"/>
<zone id="265" name="США, Нью-Йорк (NY)"/>
<zone id="267" name="США, Огайо (OH)"/>
<zone id="268" name="США, Оклахома (OK)"/>
<zone id="269" name="Канада, Онтарио (ON)"/>
<zone id="275" name="США, Орегон (OR)"/>
<zone id="276" name="США, Пенсильвания (PA)"/>
<zone id="277" name="Канада, Остров Принца Эдварда (PE)"/>
<zone id="278" name="Канада, Квебек (QC)"/>
<zone id="281" name="США, Род-Айленд"/>
<zone id="282" name="США, Южная Каролина (SC)"/>
<zone id="283" name="США, Южная Дакота (SD)"/>
<zone id="284" name="Канада, Саскачеван (SK)"/>
<zone id="285" name="США, Теннесси (TN)"/>
<zone id="286" name="США, Техас (TX)"/>
<zone id="287" name="США, Юта (UT)"/>
<zone id="288" name="США, Вирджиния (VA)"/>
<zone id="290" name="США, Вермонт (VT)"/>
<zone id="291" name="США, Вашингтон (WA)"/>
<zone id="293" name="США, Висконсин (WI)"/>
<zone id="294" name="США, Западная Вирджиния (WV)"/>
<zone id="295" name="США, Вайоминг (WY)"/>
<zone id="296" name="Канада, Юкон (YT)"/>
<zone id="297" name="США, Коннектикут (CT)"/>
<zone id="298" name="США, Алабама (AL)"/>
<zone id="300" name="Акмолинская область (Кокшетау)"/>
<zone id="301" name="Актюбинская область (Актобе)"/>
<zone id="302" name="Алматинская область (Талдыкорган)"/>
<zone id="303" name="Алматы (Алматы)"/>
<zone id="304" name="Астана (Астана)"/>
<zone id="305" name="Атырауская область (Атырау)"/>
<zone id="306" name="Байконур (Байконур)"/>
<zone id="307" name="Восточно-Казахстанская область (Усть-Каменогорск)"/>
<zone id="308" name="Жамбылская область (Тараз)"/>
<zone id="309" name="Западно-Казахстанская область (Уральск)"/>
<zone id="310" name="Карагандинская область (Караганда)"/>
<zone id="311" name="Костанайская область (Костанай)"/>
<zone id="312" name="Кызылординская область (Кызылорда)"/>
<zone id="313" name="Мангистауская область (Актау)"/>
<zone id="314" name="Павлодарская область (Павлодар)"/>
<zone id="315" name="Северо-Казахстанская область (Петропавловск)"/>
<zone id="316" name="Южно-Казахстанская область (Шымкент)"/>
<zone id="320" name="Тайланд"/>
<zone id="322" name="Индия"/>
<zone id="325" name="Китай"/>
<zone id="327" name="Южная Корея"/>
<zone id="330" name="Финляндия"/>
<zone id="331" name="Узбекистан"/>
<zone id="337" name="Кипр"/>
<zone id="351" name="Бельгия"/>
<zone id="355" name="Швейцария"/>
<zone id="357" name="Ирландия"/>
<zone id="361" name="Норвегия"/>
<zone id="362" name="Дания"/>
<zone id="372" name="Эстония"/>
<zone id="373" name="Литва"/>
<zone id="374" name="Грузия"/>
<zone id="375" name="Молдавия"/>
<zone id="376" name="Армения"/>
<zone id="377" name="Киргизия"/>
<zone id="378" name="Азербайджан"/>
<zone id="379" name="Туркменистан"/>
<zone id="380" name="Чехия"/>
<zone id="381" name="Словакия"/>
<zone id="382" name="Болгария"/>
<zone id="383" name="Румыния"/>
<zone id="384" name="Словения"/>
<zone id="385" name="Сербия"/>
<zone id="390" name="Венгрия"/>
</geoTargeting>
</content>
</entry>
Код ответа 200.
1.2. Просмотр списка геозон для сценария
Нижеследующий запрос позволяет получить список всех настроенных геотаргетингов заданного сценария (в примере – сценария 791628).
GET/adplacements/791628/targeting/geo Content-Type:application/atom+xml X-Auth-UserID:174291 X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%3E
В ответ система возвращает все текущие данные по всем геотаргетингам запрошенного идентификатора сценария.
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-05T15:04:20+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Geo Targeting Atom Entry</title>
<id>https://api.adriver.ru/adplacements/791628/targeting/geo</id>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791628"/>
<content type="text/xml">
<geoTargeting xmlns="http://adriver.ru/ns/restapi/atom">
<zone id="33">1</zone>
<zone id="38">1</zone>
</geoTargeting>
</content>
</entry>
Примечания к коду:
- 33, 38 — геозоны.
Код ответа 200.
1.3. Редактирование списка настроенных геозон для сценария
Запрос на редактирование списка настроенных геозон сценария позволяет добавить необходимые новые геозоны в список, а также отключить те или иные геозоны, добавленные ранее. Нижеследующий запрос отключает таргетинг сценария на Москву и Московскую область и добавляет таргетинг на Киев и Киевскую область:
PUT/adplacements/791628/targeting/geo
Content-Type:application/atom+xml
X-Auth-UserID:174291
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%3E
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-08-23T12:50:16+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Geo Targeting Atom Entry</title>
<content type="text/xml">
<geoTargeting xmlns="http://adriver.ru/ns/restapi/atom">
<zone id="33">1</zone>
<zone id="38">0</zone>
<zone id="110">1</zone>
</geoTargeting>
</content>
</entry>
Примечания к коду:
- <zone id=”38″>0</zone> — Геозона 38 исключается из списка настроенных геозон данного сценария.
- <zone id=”110″>1</zone> — Геозона 110 добавляется к списку настроенных геозон данного сценария.
В случае успешного редактирования в ответе возвращаются все текущие данные по всем геотаргетингам:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-05T15:10:50+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Geo Targeting Atom Entry</title>
<id>https://api.adriver.ru/adplacements/791628/targeting/geo</id>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791628"/>
<content type="text/xml">
<geoTargeting xmlns="http://adriver.ru/ns/restapi/atom">
<zone id="33">1</zone>
<zone id="110">1</zone>
</geoTargeting>
</content>
</entry>
Код ответа 200.
Если, например, в запросе на редактирование была задана несуществующая геозона, ответ системы будет выглядеть следующим образом:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-04-06T13:56:12+04:00</updated>
<content type="text">unknown geozone ids: [391]</content>
<summary>Adriver::RestAPI::Core::Exception::BadRequest</summary>
</entry>
Код ответа 400.
1.4. Удаление настроенного геотаргетинга
Пример запроса на удаление всех настроенных ранее геозон:
DELETE/adplacements/791628/targeting/geo Content-Type:application/atom+xml X-Auth-UserID:179221 X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%3E
Код ответа 200 (в случае успешного выполнения операции).
Если в запросе был задан несуществующий идентификатор сценария, ответ системы будет выглядеть следующим образом:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-04-06T15:44:04+04:00</updated>
<content type="text">AdPlacement (id 7916281) not found</content>
<summary>Adriver::RestAPI::Core::Exception::AdPlacement::NotFound</summary>
</entry>
Код ответа 404.
Если же в запросе был задан существующий идентификатор сценария, принадлежащий другой учетной записи, то ответ системы будет выглядеть так:
?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-04-06T15:44:33+04:00</updated>
<content type="text">Not authorized to work with object [Adriver::API::AdPlacementX]</content>
<summary>Adriver::RestAPI::Core::Exception::UnAuthorized</summary>
</entry>
Код ответа 401.