REST API MGID для рекламодателей

Contents

Основные положения REST API

REST API MGID  позволяет  интегрировать внешние приложения с системой  интернет-рекламы MGID.

API дает возможность извлекать, добавлять и изменять данные. Практически   каждым объектом в MGID (будь то клиент, рекламная компания, тизер и т.д.) можно  управлять с помощью API.

Запрос  MGID REST API – это   HTTP запрос, в котором, с помощью  путей  в URL  задается объект для выполнения действия, а с помощью параметров передаются необходимые данные. MGID API является "RESTful Web API".

Параметры запросов являются регистрозависимыми.

API использует  следующие команды REST:

  • GET
  • PUT
  • PATCH
  • POST
  • DELETE

Эти команды соответствуют определенным действия внутри системы MGID.

Команда Действие Описание
POST Создать Создание новый элемента (например, тизера)
GET Получить (чтение) Получить элемент или коллекцию  элементов (например, список рекламных кампаний)
PUT Обновить Пересоздать существующий элемент или коллекцию элементов
PATCH Изменить Изменить определенные свойства элемента
DELETE Удалять Удалить элемент или коллекцию элементов (например, переместить тизер в корзину)

Важно! POST и PUT не являются взаимозаменяемыми.

Каждая из команд выполняет свою определенную функцию.

API MGID URL

REST API MGID для клиента доступен по адресу:

http://api.mgid.com/v1

В общем виде запрос выглядит как

Идентификация

Для идентификации в REST API MGID используется уникальный токен, состоящий из 32 символов и передаваемый в запросе клиента.

Для получения действующего токена  клиент должен воспользоваться специальной функцией API

Каждый запрос, отправленный к REST API MGID обязательно  должен содержать токен API.

Ответ REST API MGID

В ответ на запрос к REST API сервер  всегда  возвращает HTTP ответ с кодом состояния, зависящего от результата запроса.

Код ответа Описание
200 OK Запрос был успешно обработан.

Формат возвращаемых данных

Возвращаемые данные могут быть  в формате  JSON, либо — XML.

По умолчанию используется формат  JSON.

Для задания формата, в котором будут возвращаться данные, используется заголовок запроса. Клиент отсылает заголовок Accept, в котором указывает желаемый формат ответа:

Accept: application/xml

или

Accept: application/json

Описание формата ответа отправляется в ответе в заголовке Content-Type.

Возвращаемые  в ответе данные, представляют собой JSON строку (http://json.org/json-ru.html), которая в общем виде,  выглядит  следующим образом:

{  
       "элемент_1":"значение_элемента_1",
       "элемент_2":"значение_элемента_2",
       "элемент_3":       {  
               "свойство_1_элемента_3":"значение_свойства_1_элемента_3",
               "свойство_2_элемента_3":               [  
                      "значение_1_свойства_2_элемента_3",
                      "значение_2_свойства_2_элемента_3" 
      ]          
   },
      . . . .
}

Если в ходе выполнения запроса произошла ошибка — возвращается описание соответствующей ошибки, например:

{
   "errors":
   [
        "[_описание_ошибки_]"
   ]
}

Данные в ответах возвращаются с учетом тайм-зоны клиента

Работа с клиентами

Получение действующего токена клиента

Метод POST
URL api.mgid.com/v1/auth/token

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
email Адрес электронной почты клиента, указанный при регистрации в системе MGID
password Пароль клиента, полученный при регистрации

Возвращаемый ответ:

{

    "token":"_текущий_токен_",

    "refreshToken":"_токен_для_обновления_"

    "idAuth":"_идентификатор_учетной_записи_клиента_"

}

_текущий_токен_  используется для идентификации  клиента;

_токен_для_обновления_ - будет использован в последующих версиях для обновления просроченного текущего токена.

Получение информации о текущем финансовом состоянии клиента

Метод GET
URL api.mgid.com/v1/clients/_идентификатор_учетной_записи_клиента_?token=_токен_клиента_

Возвращаемый ответ:

{
  "id":_идентификатор_учетной_записи_клиента_,
  "timezone":_таймзона_клиента_,
  "wallet":{          
    "balance":_состояние_МГ_кошелька_ ,
    "credit":_размер_установленного_овердрафта_,
    "income":_общая_сумма_пополнений_кошелька_,
    "currency":_валюта_клиента_
  }
}

Все суммы возвращаются в валюте клиента(доллар/руб/грн).

balance может иметь как положительное, так и отрицательное значение.

Доступные клиенту средства определяются как:   balance + credit.

Сумма потраченных клиентом средств на рекламу:   income balance.

Работа с  рекламными кампаниями  клиента

Получение коллекции рекламных кампаний клиента

Метод GET
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_

Если не передан  _идентификатор_рекламной_кампании_  то метод возвращает  коллекцию рекламных кампаний клиента. Если идентификатор был передан, то возвращается информация только о той рекламной кампании, чей идентификатор был передан.  

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
token _токен_клиента_
fields массив свойств клиента, информацию о которых необходимо получить ( например: fields=['name','ipsFilter','domainsFilter']). Если параметр не передан, то возвращаются все свойства.

Список может включать следующие свойства:

  • id   -   идентификатор рекламной кампании;
  • language - id языка рекламной кампании
  • name – название рекламной кампании;
  • status  -  текущий  статус рекламной кампании;
  • ipsFilter — настройки фильтра по IP — адресам;
  • domainsFilter — настройки фильтра по доменам;
  • widgetsFilterUid — настройки фильтра по ID площадок;
  • limitsFilter — настройки лимитов по бюджету и кликам;
  • targets - настройки таргетинга по ОС
  • languageTargeting - настройки фильтра по языкам. Список из id языков рекламной кампании
limit включает пагинацию, ограничивая количество кампаний отображаемых на странице. 
start позволяет перемещаться по страницам пагинации. По-умолчанию - 0. 

Список языков:

id name language_code
1 English en
2 Spanish es
3 French fr
4 German de
5 Vietnamese vi
6 Dutch nl
7 Italian it
8 Portuguese pt
9 Indonesian id
10 Greek el
11 Thai th
12 Hindi hi
13 Khmer km
14 Swedish sv
15 Hungarian hu
16 Malay ms
17 Romanian ro
18 Norwegian no
19 Croatian hr
20 Polish pl
21 Finnish fi
22 Danish da
23 Filipino fil
24 Czech cs
25 Korean ko
26 Bosnian bs
27 Slovak sk
28 Japanese ja
29 Bulgarian bg
30 Slovene sl
31 Macedonian mk
32 Turkish tr
33 Estonian et
34 Armenian hy
35 Serbian sr
36 Lithuanian lt
37 Azerbaijani az
38 Latvian lv
39 Russian ru
40 Urdu ur
41 Arabic ar
42 Hebrew he
43 Chinese zh
44 Georgian ka
45 Nepali ne
46 Albanian sq
47 Bengali bn
48 Sinhalese si
49 Uzbek uz
50 Ukrainian uk
51 Tamil ta
52 Telugu te
53 Persian fa
54 Somali so
55 Tajik tg
56 Kyrgyz ky
57 Lao lo
58 Gujarati gu
59 Marathi mr
60 Malayalam ml
61 Kannada kn
62 Burmese my
63 Kazakh kk
64 Turkmen tk
65 Afrikaans af
66 Punjabi pa
67 Belarusian be
68 Swahili sw
69 Mongolian mn

Возвращаемый ответ:

{
 "_идентификатор_рекламной_кампании_":{
     "id":_идентификатор_рекламной_кампании_,
     "language":_язык_кампании_,
     "name":"_название_рекламной_кампании_",
      "status":     {
       "id":_идентификатор_состояния_,
       "name":"_название_статуса_кампании_",
       "reason":"_состояние_кампании_"       
    },
     "domainsFilter":       {
      "filterType":"_тип_фильтра_по_доменам_",
      "domainsNames":[
        "_домен_1_",
          "_домен_2_",
         .  . . . . . .
      ]         
    },
    "ipsFilter":     {
        "filterType":"_тип_фильтра_по_IP_",
        "ips":        [
         "IP_адрес_1",
         "IP_адрес_2",
         . . . . . .  
      ]
    },
      "widgetsFilterUid":{
      "filterType":"_тип_фильтра_по_площадкам_",
      "widgets":{
        "_идентификатор_площадки_1":"[_идентификатор_подисточника_1]",
        "_идентификатор_площадки_2":"[_идентификатор_подисточника_2]",
        "_идентификатор_площадки_3":"[_идентификатор_подисточника_3]",

      }
    },
      "statistics":{
       "clicks":_количество_засчитанных_кликов_за_текущие_сутки_,
      "wages":_потрачено_клиентом_за_текущие_сутки_ 
    },
      "languageTargeting":[
            "language_id_1",
            "language_id_2",
             . . . . . . 
     ],
  },
    …........
}

Возможные ошибки:

[ERROR_TOO_MANY_CAMPAIGNS_USE_PARAMS_LIMIT_AND_START] - если пользователь имеет более 500 кампаний и при запросе не указан дополнительный параметр limit

[ERROR_MAX_LIMIT_PER_PAGE_500] - если указан дополнительный параметр limit и он более 500 

Свойство  status  отображает текущий статус кампании и ее состояние

Возвращаемые значения свойства status  и их описание

id Описание
1 Кампания остановлена в связи с достижением даты окончания
2 Кампания достигла общего лимита по бюджету
3 Кампания достигла общего лимита по кликам
4 Кампания заблокирована клиентом или менеджером
5 Кампания заблокирована по причине отрицательного остатка на счету
6 Кампания не имеет лимитов и активна
7 Кампания не достигла своего дневного лимита
8 Вчера кампания достигла своего суточного лимита по кликам или бюджету и активна
9 Кампания достигла суточного лимита по бюджету
10 Кампания достигла суточного лимита по кликам
11 Кампания на паузе в связи с временными настройками
12 Кампаний остановлена т.к. клиент отложен
13 Кампания остановлена менеджером
14 Кампания удалена
15 Кампания остановлена т.к. клиент отклонён
17 Кампания остановлена по лимиту конверсий
19 Кампания остановлена за нарушение правил креатива


Свойство  ipsFilter - отображает настройки фильтра рекламной кампании по IP-адресам (для посетителей с какими IP-адресами  не должны показываться тизеры данной рекламной кампании).

_тип_фильтра_по_IP_  может принимать следующие значения:

    • off  -  фильтр отключен
    • except - фильтр «кроме» (тизеры РК отображаются всем посетителям, кроме тех, чей IP присутствует в списке для блокировки)
    • ips - список IP-адресов для фильтрации в виде массива.

_потрачено_клиентом_за_текущие_сутки_ в  валюте клиента

Получение статистики в разрезе площадок

Метод GET
URL api.mgid.com/v1/goodhits/campaigns/ид_кампании/quality-analysis/_uid_?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
token токен авторизации клиента.
campaignId идентификатор товарной кампании.
dateInterval интервал, за который нужно получить статистику. Если интервал не задан, возвращается статистика за 90 дней. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней
uid uid площадки. Если задан - отображаются данные только для этой площадки.

Возвращаемый ответ:

{  
 "_campaignId_":{
  "_dateInterval_":{  
     "_widgetUid_":{  
        "clicks":"_clicks_",
        "spent":"_spent_",
        "cpc":"_cpc_client_currency_",
        "qualityFactor": "_quality_factor_",
        "buy":"_conversions_at_the_buying_stage_",
        "buyCost":"_price_of_conversions_at_the_buying_stage_",
        "decision":"_conversions_at_the_decision_stage_",
        "decisionCost":"_price_of_conversions_at_the_decision_stage_",
        "interest":"_conversions_at_the_interest_stage_",
        "interestCost":"_price_of_conversions_at_the_interest_stage_",
        "sources": {
            "17": {
                   "clicks":"_clicks_",
                   "spent":"_spent_",
                   "cpc":"_cpc_client_currency_",
                   "qualityFactor": "_quality_factor_",
                   "buy":"_conversions_at_the_buying_stage_",
                   "buyCost":"_price_of_conversions_at_the_buying_stage_",
                   "decision":"_conversions_at_the_decision_stage_",
                   "decisionCost":"_price_of_conversions_at_the_decision_stage_",
                   "interest":"_conversions_at_the_interest_stage_",
                   "interestCost":"_price_of_conversions_at_the_interest_stage_",
            },
            "0": {
                  "clicks":"_clicks_",
                  "spent":"_spent_",
                  "cpc":"_cpc_client_currency_",
                  "qualityFactor": "_quality_factor_",
                  "buy":"_conversions_at_the_buying_stage_",
                  "buyCost":"_price_of_conversions_at_the_buying_stage_",
                  "decision":"_conversions_at_the_decision_stage_",
                  "decisionCost":"_price_of_conversions_at_the_decision_stage_",
                  "interest":"_conversions_at_the_interest_stage_",
                  "interestCost":"_price_of_conversions_at_the_interest_stage_",
            }
        }
     }
  }
}

Если в ходе выполнения запроса произошла ошибка — возвращается описание соответствующей ошибки, например:

{"errors":["[_описание_ошибки_]"]}
[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST] - виджеты с заданными uid не существуют, если в списке есть валидные uid - они запишутся в базу

{
"id":_идентификатор_рекламной_кампании_, 
"errors":"[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST]",
"data":["1000000","111111"]
}

 

Детальная статистика рекламных кампаний клиента за день

Метод GET
URL api.mgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/statistics?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры отмечены красным

Параметр Значение
type Тип статистики.Возможные значение: byClicksDetailed
date Дата в формате:YYYY-MM-DD

Возвращаемые значения

Если запрос выполнен корректно, то возвращается массив данных в следующем формате:

{
"id":_идентификатор_рекламной_кампании_,
"statistics":{
"summary":{
"numberOfClicks":_общее_количество_кликов_,
"numberOfAcceptedClicks":_количество_засчитанных_кликов_,
"fundsEarned":_потрачено_клиентом_,
"numberOfRejectedClicks":_количество_незасчитанных_кликов_,
"numberOfShows":_общее_количество_показов_
},
"acceptedClicks":[
{
"time":"_время_клика_",
"ip":"_ip_адрес_",
"teaserId":"_id_тизера_",
"informerId":"id_площадки_",
"country":"_двухсимвольный_код_страны_",
"region":"_регион_",
"price":"_цена_за_клик_"                  // _click_price_/1000 = RUR/UAH/USD
},
. . . . . . . . .]

}}

_потрачено_клиентом_  , _стоимость_клика_ -  в валюте клиента(доллар/руб/грн).

Подневная статистика рекламных кампаний клиента

Метод GET
URL api.mgid.com/v1/goodhits/clients/{clientId}/campaigns-stat?token={accessToken}

Передаваемые параметры:

Параметр Значение
token Токен клиента
dateInterval интервал, за который нужно получить статистику. Если интервал не задан, возвращается статистика за 90 дней. Допустимые значения:

interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
all - за все время
thisWeek - текущая неделя
lastWeek - прошлая неделя
thisMonth - текущий месяц
lastMonth - прошлый месяц
lastSeven - последние 7 дней
today - сегодня
yesterday - вчера
last30Days - последние 30 дней

Возвращаемый ответ:

"_campaign_id_":{
   "campaign_id":_campaign_id_,
   "imps":_кол-во_показов_,
   "clicks":_кол-во_кликов_,
   "spent":_траты_,
   "avcpc":_средняя_стоимость_клика_
}

Если у клиента настроены конверсии, то дополнительно передаются:

  • buy - количество конверсий на этапе покупка
  • buyCost - цена конверсии на этапе покупка
  • decision - количество конверсий на этапе желание
  • decisionCost - цена конверсии на этапе покупка
  • interest - количество конверсий на этапе интерес
  • interestCost - цена конверсии на этапе покупка
  • convertionCost - прибыль по конверсиям
  • revenue - заработано
  • epc - заработок за клик
  • profit - revenue - spent

Если в ходе выполнения запроса произошла ошибка — возвращается описание соответствующей ошибки, например:

{"errors":["[_описание_ошибки_]"]}
[THERE_NO_DATA_IN_CHOSEN_PERIOD] - если в заданном периоде нет данных

[INVALID_VALUE_FOR_INTERVAL] - если некорректно задан интервал или дата старта интервала больше текущей

Создание новой рекламной кампании клиента (со всеми настройками)

Метод POST
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns?token=_токен_клиента_

Передаваемые параметры (красным обязательные параметры, синим обязательные, если родительский параметр передан (включен)):

Блок 1

Параметр Значение
name Название рекламной кампании. Должно быть уникальным в разрезе клиента. 128 символов максимум.
enabledGeoTargetingFlag Флаг включения/выключения (1/ 0) гео-таргетинга.
geoTargets Список стран и городов (регионов) для таргетирования. Пример параметра {'method':'set','cities':['2'],'countries':['ru']}
language language_code рекламной кампании
languageTargets Фильтр по language_code рекламной кампании в режиме include
startDate дата старта кампании YYYY-MM-DD
campaignType product/content/push/search_feed. Если campaign_type не передан создается тип product

Возможные ошибки для этого блока параметров:

[ADVERTISE_NAME_EXISTS]
[CAMPAIGN_NAME_TOO_LONG]
[ERROR_PARAMETER_ENABLED_GEO_TARGETING_FLAG_CAN_NOT_BE_EMPTY]
[ERROR_PARAMETER_GEO_TARGETS_CAN_NOT_BE_EMPTY]
[ERROR_INVALID_PARAMETER]
[ERROR_WRONG_DATE_FORMAT]
[ERROR_NOT_VALID_CAMPAIGN_TYPE]
[ERROR_PARAMETER_LANGUAGE_TARGETS_VALUE_INVALID][ERROR_PARAMETER_LANGUAGE_TARGETS_EMPTY]

 

Блок 2
Если хотябы один из utm_source, utm_campaign, utm_medium передан, то все три обязательные

Параметр Значение
utm_source 0, 9, A Z, a z, _ + & = (до 200 символов)
utm_campaign 0, 9, A Z, a z, _ + & = (до 200 символов)
utm_medium 0, 9, A Z, a z, _ + & = (до 200 символов)
utm_custom макросы: {widget_id}/{teaser_id}/{campaign_id}/{category_id} etc

Возможные ошибки для этого блока параметров:

[UTM_TAGGING_FIELDS_MUST_NOT_BE_EMPTY]
[UTM_CUSTOM_TOO_LONG_STR]
[WRONG_UTM_CUSTOM_FORMAT]
[UTM_MEDIUM_TOO_LONG_STR]
[UTM_SOURCE_TOO_LONG_STR]
[UTM_CAMPAIGN_TOO_LONG_STR]

 

Блок 3
Если задан параметр limitType, то обязательно должен быть указан тип лимита, и как минимум какой-то из разновидностей лимита (или дневной или overall)

Параметр Значение
limitType или clicks_limits или budget_limits
dailyLimit если limitType = clicks_limits, то целое значение, если limitType = budget_limits — значение с 2 знаками после запятой (до сотых).
overallLimit если clicks_limits, то целое значение. Минимальное значение должно быть больше dailyLimit, если он задан. Если budget_limits — значение с 2 знаками после запятой (до сотых). Должно быть больше dailyLimit, если он задан.
splitDailyLimitEvenly Опция равномерного распределения трафика. 0 – откл, 1 – вкл

Возможные ошибки для этого блока параметров:

[NOT_ENOUGH_PARAMETERS]
[ERROR_NOT_VALID_TYPE]
[ERROR_GREATER_THAN_LIMIT_PER_DAY]
[MINIMAL_DAILY_BUDGET_LIMIT_ERROR]
[WRONG_USE_FLOATING_LIMIT]
[ERROR_SPLIT_DAILY_LIMIT_EVENLY_IS_AVAILABLE_IF_ONLY_DAILY_LIMIT_SET]
[ERROR_MINIMAL_DAILY_CLICKS_LIMIT_IS_ %]
[ERROR_MINIMAL_DAILY_BUDGET_LIMIT_IS_ %]
[ERROR_OVERALL_CLICKS_LIMIT_LESS_THAN_DAILY_LIMIT]
[ERROR_OVERALL_BUDGET_LIMIT_LESS_THAN_DAILY_LIMIT]

 

Блок 4

Параметр Значение
browserTargets _browser1_, _browser2_, _browser3_
osTargets _os1_,_os2_,_os3_

Возможные ошибки для этого блока параметров:

"[ERROR_NO_ENOUGH_PARAMETERS]"

Возвращаемый ответ:

{
     "id":_идентификатор_кампании_,
}

Создание новой рекламной кампании клиента

Метод POST
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns?token=_токен_клиента_

Передаваемые параметры:

Параметр Значение
name Название рекламной кампании. Должно быть уникальным в разрезе клиента.
enabledGeoTargetingFlag Флаг включения/выключения (1/ 0) гео-таргетинга.
geoTargets

(параметр обязателен, если enabledGeoTargetingFlag=1)

Список стран и городов (регионов) для таргетирования:

{'method':'set','cities':['2'],'countries':['ru']}

language language_code рекламной кампании
languageTargets Фильтр по language_code рекламной кампании в режиме include
startDate дата старта кампании YYYY-MM-DD
campaignType product/content/push/search_feed. Если campaign_type не передан создается тип product

Возвращаемый ответ:

{
     "id":_идентификатор_кампании_,
}
  • Если уже существует рекламная кампания с именем, указанным в запросе, то новая рекламная кампания не  создается  и  будет возвращено сообщение об ошибке: [ADVERTISE_NAME_EXISTS]
  • Если значения languageTargets невалидные, то будет возвращено сообщение об ошибке: [ERROR_PARAMETER_LANGUAGE_TARGETS_VALUE_INVALID]
  • Если languageTargets передали пустым, то будет возвращено сообщение об ошибке: [ERROR_PARAMETER_LANGUAGE_TARGETS_EMPTY]

Получение даты создания рекламной кампании

Метод GET
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_&fields=['whenAdd']

Передаваемые параметры:

Параметр Значение
fields whenAdd

Возвращаемые значения:

{

"id":_идентификатор_рекламной_кампании_,

"whenAdd":_дата_добавления_

}

Настройки UTM меток кампании

Метод PUT
URL api.mgid.com/v1/goodhits/campaigns/_campaign_ID_/utmtracking/? token=_client's_token

Передаваемые параметры:

Параметр Значение
utm_source Стандартная настройка Google Analytics для отслеживания источника трафика
utm_campaign Стандартная настройка Google Analytics для отслеживания кампании
utm_medium Стандартная настройка Google Analytics для отслеживания канала
utm_custom Пользовательская разметка. Которая может быть добавлена в пользовательскую ссылку

Значения для  Google Analytics (utm_source, utm_campaign, utm_medium) должны быть установлены в одном запросе. При использовании одного из этих параметров, другие необходимы. Ошибка если одно из значений пустое: [UTM_TAGGING_FIELDS_MUST_NOT_BE_EMPTY]  

Когда вы включаете настройки по умолчанию для Google Analytics система автоматически добавляет utm_content  и utm_term . В Тег utm_content  автоматически добавляется ID тизера.  utm_term=_site_ID_

UTM-хвосты не должны превышать кол-во более 200 символов, в противном случае система вернет ошибку: [UTM_CUSTOM_TOO_LONG_STR]  


Приемлемые значения: 0 9, A Z, a z,   _ + & = . И макросы: {widget_id},  {teaser_id}, {campaign_id}, {category_id}.  


Или система вернет ошибку:  [WRONG_UTM_CUSTOM_FORMAT]

Если поле пустое, то поле будет отключено. Если все настроено корректно, система вернет ID кампании:

{
"id":_campaign_ID_
}

Установка лимитов рекламной кампании

Метод PATCH
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_

Передаваемые параметры отправляются в body запроса (обязательные параметры выделены красным):

Параметр Значение
limitType clicks_limits — установка лимита по кликам

budget_limits — установка лимита по бюджету

dailyLimit Установка лимита в сутки.

Для clicks_limits должно  быть целое значение. Если значение пустое — лимит отсутствует (кампания не имеет ограничения).

Для budget_limits — значение с 2 знаками после запятой (до сотых). Если значение пустое — лимит отсутствует (кампания не имеет ограничения).

overallLimit Установка лимита на кампанию в целом.

Для clicks_limits должно  быть целое значение. Минимальное значение должно быть больше dailyLimit, если он задан. Если значение пустое — лимит отсутствует (кампания не имеет ограничения).

Для budget_limits — значение с 2 знаками после запятой (до сотых). Должно быть больше dailyLimit, если он задан. Если значение пустое — лимит отсутствует (кампания не имеет ограничения).

splitDailyLimitEvenly Опция равномерного распределения трафика. 0 - откл, 1 - вкл
  • При выборе лимита по бюджету в зависимости от валюты клиента значение вводится в валюте, указанной для этого клиента.
  • Суточный лимит не может быть меньше 10$. Общий лимит не может быть меньше чем суточный лимит
  • Минимальные лимиты в рублях и гривнах равняются лимитам в долларах, умноженным на курс 50 для рублей и 25 для гривен
  • При установке лимита в рублях и гривнах шаг изменения - 5 копеек, а для долларов - 1 цент. При вводе числа, не кратного шагу - оно округляется в большую сторону.

При успешном сохранении настроек возвращается идентификатор редактируемой РК:

{
"id":_идентификатор_рекламной_кампании_
}

Блокировка/разблокировка рекламной кампании

Метод PATCH
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_

Передаваемые параметры отправляются в body запроса (обязательные параметры выделены красным):

Параметр Значение
whetherToBlockByClient 0 – разблокировать РК

1 — блокировать РК

Установка коэффициента селективного аукциона рекламной кампании

Метод PATCH
URL api.mgid.com/v1/goodhits/clients/_идентификатор_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_

Передаваемые параметры отправляются в body запроса (обязательные параметры выделены красным):

Параметр Значение
qualityFactor содержит widgetUID и новый коэффициент качества на площадку. Передается в json формате. Может быть несколько пар: {"_widgetUid1_":_qf1_,"_widgetUid2_s_sourceId2_":_qf2_,"_widgetUid3_":_qf3_}. 

Возвращаемый ответ:

{  
"id":_идентификатор_рекламной_кампании_"
}

Возможные ошибки:

  • ERROR_CAMPAIGN_USES_AUTORETARGETING_CANT_CHANGE_QF- включен авторетаргетинг
  • ERROR_CAMPAIGN_USES_PRICE_OPTIMIZATION_CANT_CHANGE_QF- включена автооптимизация
  • ERROR_CAMPAIGN_IS_DSP_CANT_CHANGE_QF- DSP кампания
  • ERROR_QUALITY_FACTOR_INVALID_FORMAT - неправильный формат данных в параметре qualityFactor
  • ERROR_WIDGETUID_INVALID_FORMAT - неправильный формат данных в параметре _widgetUid2_or _widgetUid2_s_sourceId2_

Установка коэффициента селективного аукциона для всех подисточников

Метод PATCH
URL api.mgid.com/v1/goodhits/clients/_идентификатор_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_

Передаваемые параметры отправляются в body запроса (обязательные параметры выделены красным):

Параметр Значение
widgetQualityFactor {"_widgetUid1_":_qf1_,"_widgetUid2_":_qf2_,"_widgetUid3_":_qf3_}

Возвращаемый ответ:

{  
"id":_идентификатор_рекламной_кампании_"
}

Возможные ошибки:

  • ERROR_CAMPAIGN_USES_AUTORETARGETING_CANT_CHANGE_QF- включен авторетаргетинг
  • ERROR_CAMPAIGN_USES_PRICE_OPTIMIZATION_CANT_CHANGE_QF- включена автооптимизация
  • ERROR_CAMPAIGN_IS_DSP_CANT_CHANGE_QF- DSP кампания
  • ERROR_WIDGET_QUALITY_FACTOR_INVALID_FORMAT - неправильный формат данных в параметре widgetQualityFactor
  • ERROR_WIDGETUID_INVALID_FORMAT - неправильный формат данных в параметре _widgetUid2_

Получение настроек конверсий РК

Метод GET
URL api.mgid.com/v1/goodhits/campaigns/_campaign_ID_/conversions?token=_client's_token

В ответе приходит массив из настроек конверсий РК.
Массив может быть:

  • пустым (нет никаких настроек)
  • с тремя элементами (все этапы конверсий с настройками)
  • от одного до трех элементов (настроена только часть этапов)

Внутри каждого элемента будет следующая информация:

  • stage - название этапа конверсии
  • target_id - ID существующей цели, которая привязана к указанному этапу.
  • type - тип конверсии. Доступные варианты: 'url', 'event', 'visited', 'regexp' и 'postback'.
  • conditions - настройки сработки конверсии.
  • conditions.[i].type - вид условия сработки. Доступные варианты: 'contain', 'starts', 'ends', 'visited', 'regexp' и 'postback'.
  • conditions.[i].value - значение для условия сработки.
  • price - цена за конверсию в валюте клиента. Либо будет цена числом, либо 0, если цена не указана.

Ответ:

[
    {
        "stage": _stage_,
        "target_id": _target_id_,
        "type": _target_type_,
        "conditions": [
            {
                "type": _confition_type1_,
                "value": _condition_value1_
            },
            {
                "type": _confition_type2_,
                "value": _condition_value2_
            }
        ],
        "price": _price_of_conversion_
    },
    ...
]

Ответ с этапом buy:

[
    {
        "stage": "buy",
        "target_id": 59041,
        "type": "url",
        "conditions": [
            {
                "type": "contain",
                "value": "thankyou.php"
            }
        ],
        "price": 123.123457
    }
]

Изменение настроек конверсий РК

Метод PUT
URL api.mgid.com/v1/goodhits/campaigns/_campaign_ID_/conversions?token=_client's_token

Передаваемые параметры отправляются в body запроса:

Параметр Значение
buy настройки для этапа buy
decision настройки для этапа decision
interest настройки для этапа interest

Формат значения: _target_id_,_price_

  • _target_id_ - ID существующей цели
  • _price_ - цена за конверсию в валюте клиента. Либо число, либо null.

Передача пустого массива подразумевает удаление настроек.

Ответ:

{
    "id":_campaign_id_
}

Список возможных ошибок:

[ERROR_NOT_VALID_CAMPAIGN_ID] - не валидный ID кампании (ноль или не валидный ID)
[ERROR_CAMPAIGN_DOES_NOT_EXIST] - кампания с таким ID не существует или принадлежит другому клиенту
[ERROR_CAMPAIGN_HAS_ANOTHER_CONVERSIONS_DATA_SOURCE] - у кампании настроен другой источник получения конверсий (GA, YM или GTM)
[TARGET_ID_EMPTY] - не передан ID цели
[CONVERSION_TARGET_UNIQUE_ERROR] - не нескольких этапов используется одинаковая цель
[TARGET_ID_INVALID] - несуществующая цель или цель другого клиента

Настройки геотаргетинга рекламных кампаний

Получение  настроек геотаргетинга рекламных кампаний клиента

Метод GET
URL api.mgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/targetings/geo?token=_токен_клиента_

Возвращаемый ответ:

{
      "targets":      {
               "actual":               {
                       "countries":                       {
                              "_код_страны_":                             {
                                     "code":"_код_страны_",
                                     "name":"_название_страны_",
                                     "cities":                                     [
                                            "_идентификатор_города_":                                            {
                                                    "id":_идентификатор_города_,
                                                    "name":"_название_города",
                                                    "normalizedName":"_название_латиницей_"                                                
                  },
                                          …....

                       
               ]                                  
            }                            …...

               
         }                    
      },
                 "requested":                 {
                        "countries":                        {
                                "_код_страны_":                                {
                                        "code":"_код_страны_",
                                        "name":"_название_страны_",
                                        "cities":                                        [
                                               "_идентификатор_города_":                                              {
                                                     "id":_идентификатор_города_,
                                                     "name":"_название_города",
                                                     "normalizedName":"_название_латиницей_"                                                  
                  },
                                            …....

                        
               ]                                   
            }                            
         }                     
      }              
   }
}

Секция   "actual"  -  содержит текущие настройки геотаргетинга.

Секция   "requested"  -  обновленные  настройки геотаргетинга, которые будут применены (или в ближайшее время или со следующих суток).
Если настройки геотаргетинга не используются, то возвращается ответ вида:

{
      "targets":{
             "actual":{
                    "countries":[

         ]                
      },
             "requested":{
                    "countries":[

         ]                
      }         
   }
}

Получение списка доступных стран для настройки геотаргетинга

Метод GET
URL api.mgid.com/v1/dictionaries/geo?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
type countries

Возвращает массив  стран, которые могут использоваться для настроек геотаргетинга:

[
        {
           "code":"_двухсимвольный_код_страны_",
           "name":"_название_страны_"        
   },
    …..
]

Получение списка доступных регионов (городов) для настройки геотаргетинга

Метод GET
URL api.mgid.com/v1/dictionaries/geo?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение Комментарий
type cities
countries ['_двухсимвольный_код_страны_', ….] Массив кодов стран, для которых необходимо получить список городов(регионов)

Возвращает массив регионов (городов), которые могут использоваться для настроек геотаргетинга:

[
         {
             "id":_идентификатор_города_,
             "name":"_название_города_",
             "normalizedName":"_название_города_латиницей_",
             "countryCode":"_двухсимвольный_код_страны_"         
   },
     …...
]

Редактирование настроек геотаргетинга для рекламной кампании

Метод PUT
URL api.mgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/targetings/geo?token=_токен_клиента_  

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
targets Список стран и городов (регионов) для таргетирования:

{ 'method':'set',  'cities': [  _идентификатор_города_,  . . . .   ],

    'countries':     [   _двухсимвольный_код_страны_,  . . . .   ]}

Если в параметрах переданы заполненными cities и countries - то в приоритете будет countries.

Список городов можно получить с помощью запроса.

Список стран можно получить с помощью запроса.

enabledFlag Флаг включения/выключения геотаргетинга (1/0)

Если запрос составлен корректно, будет возвращен id редактируемой РК:

{
    "id":_идентификатор_рекламной_кампании
}

Если не указаны какие-либо параметры или указаны не верно, то изменения настроек не сохранятся и  будет возвращено сообщение об ошибке:

{
    "errors":
    [
         "[ERROR_NO_ENOUGH_PARAMETERS]"
    ]
}

Редактирование настроек таргетинга по браузерам для рекламной кампании

Метод PUT
URL api.mgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/targetings/browsers?token=_токен_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
targets _метод_редактирования_ , _браузер_,_браузер_.....
enabledFlag 0 – таргетинг выключен

1 — таргетинг включен

Возможные значений  для _метод_редактирования_ :

include   -  включение браузера в список для таргетинга

Возможные значения для _браузер_ :

Название Значение
Google Chrome chrome
Safari safari
Opera Mini operamini
Opera Mobile operamoblie
Opera opera
Firefox firefox
Internet Explorer msie
Others others

При успешном сохранении настроек возвращается идентификатор редактируемой РК:

{
    "id":_идентификатор_рекламной_кампании_
}

Редактирование настроек фильтра по IP-адресам для рекламной кампании

Метод PATCH
URL api.mgid.com/v1/goodhits/clients/_идентификатор_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_

Передаваемые параметры отправляются в body запроса (обязательные параметры выделены красным):

Параметр Значение
ipsFilter _метод_редактирования_ ,  _тип_фильтра_, IP1,IP2….

Поддерживаются такие настройки :

  • Методы редактирования :
    • include    -  включить адрес в список
    • exclude   - удалить адрес из списка
  • Типы фильтра :
    • except   -  кроме
    • only   -  только
    • off  -   отключен

IP можно указывать как единичные, так и в виде подсетей (192.168.0.1/24)

При успешном сохранении настроек возвращается идентификатор редактируемой РК:

{
  "id":_идентификатор_рекламной_кампании_
}

Редактирование настроек фильтра по ОС для рекламной кампании

Метод PUT
URL api.mgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/targetings/operatingsystems?token=_токен_

Передаваемые параметры:

Параметр Значение
enabledFlag вкл/выкл ОС таргетинг,

вкл=1

выкл=0

targets _метод_редактирования_,_os_code1_,_os_code2_,_os_code3_

Операционные системы:

id name version os_code
8 Windows OS Other windowsos
9 Mac OS Other macos
10 Other Desktop OS otherdesctop
11 Android 2.2 and lower android22mobile
12 Android 2,3 android23mobile
13 Android 3.хх android3mobile
14 Android 4 android40mobile
15 Android 4,1 android41mobile
16 Android 4,2 android42mobile
17 Android 4,3 android43mobile
18 Android 4,4 android44mobile
19 iOS 4.хх and lower ios4mobile
20 iOS 5.хх ios5mobile
21 iOS 6.хх ios6mobile
22 iOS 7.хх ios7mobile
23 iOS 8.хх ios8mobile
24 Other Mobile OS othermobile
25 Android 2.2 and lower android22tablet
26 Android 2,3 android23tablet
27 Android 3.хх android3tablet
28 Android 4 android40tablet
29 Android 4,1 android41tablet
30 Android 4,2 android42tablet
31 Android 4,3 android43tablet
32 Android 4,4 android44tablet
33 iOS 4.хх and lower ios4tablet
34 iOS 5.хх ios5tablet
35 iOS 6.хх ios6tablet
36 iOS 7.хх ios7tablet
37 iOS 8.хх ios8tablet
38 Other Tablet OS othertablet
39 Android 5.xx android50mobile
40 Android 5.xx android50tablet
41 iOS 9.хх ios9tablet
42 iOS 9.хх ios9mobile
43 Android 6.xx android60mobile
44 Android 6.xx android60tablet
45 iOS 10.хх ios10mobile
46 iOS 10.хх ios70tablet
47 Android 7.xx android70tablet
48 Android 7.xx android70mobile
50 iOS 11.xx ios11mobile
51 iOS 11.xx ios11tablet
53 Android 8.xx android80mobile
54 Android 8.xx android80tablet
55 Android 9.xx android90mobile
56 Android 9.xx android90tablet
57 iOS 12.xx ios12mobile
58 iOS 12.xx ios12tablet
59 Android 10.хх android10mobile
60 Android 10.хх android10tablet
61 iOS 13.хх ios13mobile
62 iOS 13.хх ios13tablet
63 Windows OS 10 windowsos10
64 Windows OS 8,1 windowsos81
65 Windows OS 8 windowsos8
66 Windows OS 7 windowsos7
67 Windows OS Vista windowsosvista
68 Windows OS XP windowsosxp
69 Mac OS 10.12 Sierra macos1012
70 Mac OS 10.13 High Sierra macos1013
71 Mac OS 10.14 Mojave macos1014
72 Mac OS 10.15 Catalina macos1015
73 Other Smart TV othersmarttv
74 Android androidsmarttv
75 Fire OS (Amazon) fireossmarttv
76 tvOS (Apple TV) tvossmarttv
77 Tizen tizenossmarttv
78 webOS webossmarttv
  • Методы редактирования :
    • include - включить адрес в список
    • exclude - удалить адрес из списка

При успешном сохранении настроек возвращается идентификатор редактируемой РК:

{
  "id":_идентификатор_рекламной_кампании_
}

Редактирование настроек фильтра по площадкам для ТРК с помощью UID

Метод PATCH
URL api.mgid.com/v1/goodhits/clients/_идентификатор_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_

Передаваемые параметры отправляются в body запроса:

Параметр Значение
widgetsFilterUid метод_редактирования, тип_фильтра, uid1,uid2…

можно передавать параметры подисточника в скобках через пробел

тип_фильтра, uid1(subid subid subid),uid2… или через "s"

тип_фильтра, UID1sSUBID1

block-widget-priority Используйте этот параметр, если хотите, чтобы при отправке вашего запроса на добавление sub_id (метод include) запрос игнорировался в том случае, если в фильтрах уже добавлена родительская площадка данного sub_id.

Пример запроса:

api.mgid.com/v1/goodhits/clients/{id клиента}/campaigns/{id кампании}?token={токен}&widgetsFilterUid=include, only, {id виджета}s{id подисточника}&block-widget-priority

Методы редактирования :

  • include - включить адрес в список
  • exclude - удалить адрес из списка

Типы фильтра:

  • only - только
  • except - кроме
  • off - фильтр отключен


При успешном сохранении настроек возвращается идентификатор редактируемой РК:

{
  "id":_идентификатор_рекламной_кампании_
}

Пример ответа с ошибками в данных - не переданы площадки:

{
  "errors":["[WIDGETS_IDS_CANNOT_BE_EMPTY]"]
}

Пример ответа с ошибками в данных - переданы не существующие id площадок:

{
  "errors":["[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST]"],"data":["1000000001000"]
}

Пример ответа с ошибками в данных - не переданы параметры фильтров(include|exclude,off|only|except) или переданы неправильно:

{
  "errors":["[ERROR_NOT_VALID_FILTER_TYPE]"]
}

Если передали валидные и не валидные ID одновременно ("widgetsFilter": "include, only, ttttts1, 5676301111, 5676672rrr, eeeeee") - в этом случае валидные запишутся в базу, а не валидные выдаст в ответ:

{"id":_ad_campaign_ID_, "errors":"[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST]","data":["ttttts1","5676672rrr","eeeeee"]}

Ситуация, когда не передаются площадки - является НЕ валидной.

При смене типа фильтра с 1 на 2 или наоборот возвращается ошибка:

[ERROR_CURRENT_FILTER_TYPE_DIFFERENT_FIRST_SEND_OFF_FOR_FILTER_THAN_SEND_NEW_FILTER_TYPE]

Работа с тизерами клиента

Используемые константы и идентификаторы

Код валюты для отображения цены товара

id combname name_utf
1 rub руб
4 uah грн
5 usd $
6 eur
9 byn руб
12 inr
23 ils
35 gel
38 kzt
43 aed د.إ
46 inr

Статусы тизера

Обозначение  статуса Описание
onModeration Тизер находится на модерации
rejected Тизер отклонен
active Тизер активен
new Новый тизер, еще не заработал собственный CTR
goodPerformance Тизер находится в показах во всех
badPerformance Тизер не показывается в одном или нескольких регионах из-за низкого рейтинга. Необходимо установить более высокую цену за клик  или заменить тизер на другой, который мог бы обеспечить более высокий CTR
blocked Тизер заблокирован
campaignBlocked Заблокирована рекламная кампания

Получение коллекции тизеров клиента

Метод GET
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers[/_идентификатор_тизера_]

Если _идентификатор_тизера_ не передан,  то метод возвращает  коллекцию тизеров клиента. Если идентификатор  передан, то возвращается информация только о том тизере, идентификатор которого был передан в запросе.  

Передаваемые параметры

Обязательные параметры отмечены красным

Параметр Значение
token _токен_клиента_
fields

(используется если в запросе передан _идентификатор_тизера_)

Массив  свойств тизера, информацию о которых необходимо получить ( например: fields=['title','url','statistics']). Если параметр не передан, то возвращаются все свойства.
status Принимает значения из таблицы "Статусы тизера"; можно указать несколько статусов одновременно (например: status=['active','onModeration']) для получения всех тизеров с данными статусами.
campaign получение товарных тизеров клиента по ID кампании
limit включает пагинацию, ограничивая количество тизеров отображаемых на странице. Если лимит не указан - отображаются все тизеры. Возможные ошибки при использовании опции limit: ["[ERROR_MAX_LIMIT_PER_PAGE_{max_allowed_limit}]"]
start задает позицию элемента. По-умолчанию - 0. Например: при первом запросе start = 0 limit = 700, следующий запрос будет выглядеть так
start = 700 limit = 700. 

Возвращаемый ответ:

{
         "_идентификатор_тизера_": {
              "id":"_идентификатор_тизера_",
              "title":"_заголовок_тизера_",
              "advertText":"_рекламный_текст_тизера_",
              "url":"_рекламная_ссылка_",
              "imageLink":"_ссылка_на_изображение_для_тизера_",
              "cropLeft":"_обрезка_изображения_слева_",
              "cropTop":"_обрезка_изображения_сверху_",
              "cropWidth":"_ширина_вырезаемой_части_",
              "priceOfClickByLocations":[{
                  "locationId":"_идентификатор_гео_группы_",
                  "locationName":"_название_гео_группы_",
                  "priceOfClick":"_цена_за_клик_по_гео_группе"
               },
              ... ]       
              "goodPrice":_цена_товара_,
              "goodOldPrice":_старая_цена_товара_,
              "currency":_идентификатор_валюты_для_отображения_цены_товара_,
              "campaignId":_идентификатор_кампании_,
              "status":"_статус_тизера_",
              "reason_if_drop_karantin":_причина _отклонения_ (отображается если тизер отклонен),
              "statistics": {
                  "clicks":_кликов_всего_,
                  "clicks_today":_клики_за_сегодня_,
                  "clicks_yesterday":_клики_за_вчера_,
                  "hits":_показов_всего_,
                  "hits_today":_показов_за_сегодня_,
                  "hits_yesterday":_показов_за_вчера_,
                  "spent":_потрачено_всего,
                  "spent_today":_потрачено_за_сегодня,
                  "spent_yesterday":_потрачено_за_вчера,
                  "ctr":"_CTR_тизера_",
                  "ctr_by_locations":[{
                      "locationId":"_идентификатор_гео_группы_",
                      "locationName":"_название_гео_группы_",
                      "ctr":"_ctr_по_гео_группе"
                  },
                  ... ]            
              "conversion":        {
                  "interest_all":_количество_достижений_этапа_интерес_за_все_время_,
                  "decision_all":_количество_достижений_этапа_решение_за_все_время_,
                  "buying_all":_количество_достижений_этапа_покупка_за_все_время_,
                  "interest_yesterday":_количество_достижений_этапа_интерес_за_вчера_,
                  "decision_yesterday":_количество_достижений_этапа_решение_за_вчера_,
                  "buying_yesterday":_количество_достижений_этапа_покупка_за_вчера_
              }            
         },
           "_идентификатор_тизера_2_":       {
              . . . . . .

    
   },
     . . . . . . . . .
}

Синим цветом шрифта выделен ответ, возвращаемый, если в запросе был передан идентификатор  тизера. Если в запросе был передан идентификатор  несуществующего тизера или тизера, принадлежащего  другому клиенту будет возвращено сообщение об ошибке:

{
"errors":
 ["Entity was not found."]
}

Создание нового тизера для рекламной кампании клиента

Метод POST
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers?token=_токен_клиента_

Передаваемые параметры (необходимо передавать в body POST-метода)

Обязательные параметры отмечены красным.

Параметр Значение
url URL рекламной ссылки. При передаче параметров рекомендовано использовать %26 вместо &
campaignId Идентификатор рекламной кампании
title Заголовок тизера

  • для кампаний с типом content/product - до 65 символов
  • для кампаний с типом push - до 30 символов
advertText Рекламный текст. Если данный параметр передан в запросе, то валидация будет следующая:

  • для кампаний с типом content/product - до 75 символов (опционально)
  • для кампаний с типом push - до 40 символов (обязательно)

Если параметр не был передан - он не будет изменен.

imageLink Ссылка на изображение для тизера (минимум 492x328 пикселей)
category Идентификатор категории тизера
priceOfClick Цена за клик, в центах, с десятыми долями.

В качестве разделителя целой и дробной части может использоваться запятая или точка.

cropWidth Размер стороны прямоугольника, в пикселях, который будет вырезаться из загружаемого изображения (imageLink). 

  • cropWidth не может быть меньше чем 492px.
  • Если указан cropLeft - то cropWidth не может быть меньше, чем cropWidth+cropLeft и не может быть больше ширины изображения imageLink
cropTop Смещение от верхнего края, в пикселях, прямоугольника который будет вырезаться из загружаемого изображения (imageLink).

  • Если параметр передается - он может быть равен 0, но не может быть меньше, чем высота изображения imageLink минус 328px
  • Если параметр не передается, то он устанавливается в 0
cropLeft Смещение  от левого края, в пикселях, прямоугольника который будет вырезаться из загружаемого изображения (imageLink).

  • Если параметр передается - он может быть равен 0. 
  • cropWidth+cropLeft не может быть больше ширины изображения imageLink
  • Если параметр не передается, то он устанавливается в 0
cropWidthQuadratic Размер стороны квадрата, в пикселях, который будет вырезаться из загружаемого изображения (imageLink). 

  • cropWidthQuadratic не может быть меньше чем 328px.
  • Если указан cropLeftQuadratic - то cropWidthQuadratic не может быть меньше, чем cropWidthQuadratic+cropLeftQuadratic и не может быть больше ширины изображения imageLink
cropTopQuadratic Смещение от верхнего края, в пикселях, квадрата который будет вырезаться из загружаемого изображения (imageLink).

  • Если параметр передается - он может быть равен 0, но не может быть меньше, чем высота изображения imageLink минус 328px
cropLeftQuadratic Смещение  от левого края, в пикселях, квадрата который будет вырезаться из загружаемого изображения (imageLink).

  • Если параметр передается - он может быть равен 0. 
  • cropWidthQuadratic+cropLeftQuadratic не может быть больше ширины изображения imageLink
whetherShowGoodPrice Флаг отображения цены товара (1/0)

При whetherShowGoodPrice = 1 параметры currency, goodPrice, goodOldPrice обязательны.
При whetherShowGoodPrice = 0  параметры будут проигнорированы.

currency Идентификатор валюты для  отображения  цены товара
goodPrice Цена товара, в отображаемой валюте
goodOldPrice Старая цена товара

Список категорий:

category id Название Типы кампаний
100 Automotive "product", "video", "push
101 Books and Literature "product", "video", "push
102 Events and Attractions "product", "video", "push
103 Events "product", "video", "push
104 Subscriptions "product", "video", "push
105 Casinos and Gambling "product", "video", "push
106 Family and Relationships "product", "video", "push
107 Marriage and Civil Unions "product", "video", "push
108 Dating "product", "video", "push
109 Pick up "product", "video", "push
110 Food and Drink "product", "video", "push
111 World Cuisines "product", "video", "push
112 Alcoholic Beverages "product", "video", "push
113 Healthy Living "product", "video", "push
114 Nutrition "product", "video", "push
115 Weight Loss "product", "video", "push
116 Women's Health "product", "video", "push
117 Children's Health "product", "video", "push
118 Fitness and Exercise "product", "video", "push
119 Wellness "product", "video", "push
120 Alternative Medicine "product", "video", "push
121 Smoking Cessation "product", "video", "push
122 Muscle Building "product", "video", "push
123 Brain Booster "product", "video", "push
124 Home and Garden "product", "video", "push
125 Home Appliances "product", "video", "push
126 Home Security "product", "video", "push
127 Home Improvement "product", "video", "push
128 Gardening "product", "video", "push
129 Medical Health "product", "video", "push
130 Diseases and Conditions "product", "video", "push
131 Sleep Disorders "product", "video", "push
132 Diabetes "product", "video", "push
133 Varicosis "product", "video", "push
134 Bone and Joint Conditions "product", "video", "push
135 Eye and Vision Conditions "product", "video", "push
136 Psoriasis "product", "video", "push
137 Papilloma "product", "video", "push
138 Skin and Dermatology "product", "video", "push
139 Medical Services "product", "video", "push
140 Other Treatment "product", "video", "push
141 Foot Health "product", "video", "push
142 Parasites "product", "video", "push
143 Hemorrhoid "product", "video", "push
144 Prostatitis "product", "video", "push
145 Sexual Health "product", "video", "push
146 Personal Finance "product", "video", "push
147 Personal Investing "product", "video", "push
148 Stocks and Bonds "product", "video", "push
149 Options "product", "video", "push
150 Insurance "product", "video", "push
151 Personal Debt "product", "video", "push
152 Financial Assistance "product", "video", "push
153 Retirement Planning "product", "video", "push
154 Real Estate "product", "video", "push
155 Shopping "product", "video", "push
156 For Kids "product", "video", "push
157 Gifts and Souvenirs "product", "video", "push
158 Services "product", "video", "push
159 Couponing "product", "video", "push
160 Sports "product", "video", "push
161 Sporting Goods "product", "video", "push
162 Fishing Sports "product", "video", "push
163 Style and Fashion "product", "video", "push
164 Beauty "product", "video", "push
165 Makeup and Accesories "product", "video", "push
166 Natural and Organic Beauty "product", "video", "push
167 Skin Care "product", "video", "push
168 Hair Care "product", "video", "push
169 Perfume and Fragrance "product", "video", "push
170 Other Beauty Products "product", "video", "push
171 Personal Care "product", "video", "push
172 Oral Care "product", "video", "push
173 Shaving "product", "video", "push
174 Women's Fashion "product", "video", "push
175 Women's Clothing "product", "video", "push
176 Women's Intimates and Sleepwear "product", "video", "push
177 Women's Outfits "product", "video", "push
178 Women's Accessories "product", "video", "push
179 Women's Jewelry and Watches "product", "video", "push
180 Other Women's Accessories "product", "video", "push
181 Women's Shoes and Footwear "product", "video", "push
182 Men's Fashion "product", "video", "push
183 Men's Сlothing "product", "video", "push
184 Men's Underwear and Sleepwear "product", "video", "push
185 Men's Outfits "product", "video", "push
186 Men's Accesories "product", "video", "push
187 Men's Jewelry and Watches "product", "video", "push
188 Other Men's Accesories "product", "video", "push
189 Men's Shoes and Footwear "product", "video", "push
190 Children's Clothing "product", "video", "push
191 Technology and Computing "product", "video", "push
192 Computing "product", "video", "push
193 Laptops "product", "video", "push
194 Desktops "product", "video", "push
195 Computer Peripherals "product", "video", "push
196 Computer Software and Applications "product", "video", "push
197 Consumer Electronics "product", "video", "push
198 Smartphones "product", "video", "push
199 Tablets and E-readers "product", "video", "push
200 Cameras and Camcorders "product", "video", "push
201 Wearable Technology "product", "video", "push
202 Energysavers "product", "video", "push
203 Self Defense "product", "video", "push
204 Solar Panels "product", "video", "push
205 Other Electronics "product", "video", "push
206 Travel "product", "video", "push
207 Video Gaming "product", "video", "push
208 Automotive "content"
209 Business and Finance "content", "push"
210 Careers "content", "push"
211 Education "content", "push"
212 Events and Attractions "content"
213 Family and Relationships "content"
214 Society "content"
215 Parenting "content"
216 Sex "content"
217 Fine Art "content", "push"
218 Food and Drink "content"
219 Cooking "content"
220 Alcoholic Beverages "content"
221 Healthy Living "content"
222 Wellness "content"
223 Nutrition "content"
224 Fitness and Exercise "content"
225 Hobbies and Interests "content", "push"
226 Amazing "content", "push"
227 Humor "content", "push"
228 Interests "content", "push"
229 Home and Garden "content"
230 Movies "content", "push"
231 Music and Audio "content", "push"
232 News and Politics "content", "push"
233 Politics "content", "push"
234 Crime "content", "push"
235 Disasters "content", "push"
255 News "content", "push"
236 News Russia "content", "push"
237 News Ukraine "content", "push"
238 Pets "content"
239 Pop Culture "content", "push"
240 Real Estate "content"
241 Science "content", "push"
242 Sports "content"
243 Style and Fashion "content"
244 Beauty "content"
245 Fashion Trends "content"
246 Body Art "content"
247 Technology and Computing "content"
248 Television "content", "push"
249 Travel "content"
250 Video Gaming "content"
251 Pets "product", "push
253 Business and Investing "product", "push"
254 Currencies "product", "push"
255 Local News "content", "push"
256 News India "content", "push"
257 International News "content", "push"

Категории, которые являются родительскими для других категорий не могут использоваться для создания тизера

Возвращаемый ответ:

При успешном создании тизера возвращается ответ:

{
     "id":_идентификатор_созданного_тизера_,
}

Если при попытке создания тизера произошла ошибка, то  возвращается название название ошибки:

{
 "errors":
 [
  "[_НАЗВАНИЕ_ОШИБКИ_]"
 ]
}

Список возможных ошибок, возвращаемых при создании  и  редактировании  тизера рекламной кампании.

_НАЗВАНИЕ_ОШИБКИ_ Описание
ERROR_PARAMETER_WHETHERSHOWGOODPRICE_CAN_NOT_BE_EMPTY Не передан обязательный параметр  whetherShowGoodPrice
ERROR_PARAMETER_PRICEOFCLICK_CAN_NOT_BE_EMPTY Не передан обязательный параметр  priceOfClick
ERROR_PARAMETER_CATEGORY_CAN_NOT_BE_EMPTY Не передан обязательный параметр
category
ERROR_ADVERT_TEXT_TOO_LONG Рекламный текст (параметр advertText)превышает максимально допустимую длину (не более 75 символов)
ERROR_PARAMETER_TITLE_CAN_NOT_BE_EMPTY Не передан заголовок тизера (обязательный параметр title)
ERROR_TITLE_TOO_LONG Заголовок тизера (параметр  title) превышает максимально допустимую длину (не более 65 символов)
ERROR_PARAMETER_IMAGELINK_CAN_NOT_BE_EMPTY Не передана ссылка на изображение для тизера (обязательный параметр  imageLink)
ERROR_PARAMETER_CAMPAIGNID_CAN_NOT_BE_EMPTY Не передан идентификатор рекламной кампании, для которой создается тизер  (обязательный параметр  campaignId)
ERROR_PARAMETER_URL_CAN_NOT_BE_EMPTY Не передана  рекламная ссылка для тизера   (обязательный параметр url)
[ERROR_PARAMETER_CATEGORY_INCORRECT_FOR_THIS_CAMPAIGN_TYPE] Неправильно выбран параметр category для текущего типа кампании

Изменение настроек тизера рекламной кампании

Метод PUT
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers/_идентификатор_тизера_?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры отмечены красным.

Параметр Значение
url URL рекламной ссылки
campaignId Идентификатор кампании
title Заголовок тизера

  • для кампаний с типом content/product - до 65 символов
  • для кампаний с типом push - до 30 символов
advertText Рекламный текст. Если данный параметр передан в запросе, то валидация будет следующая:

  • для кампаний с типом content/product - до 75 символов (опционально)
  • для кампаний с типом push - до 40 символов (обязательно)

Если параметр не был передан - он не будет изменен.

imageLink Ссылка на изображение для тизера (минимум 492x328 пикселей)
category Идентификатор категории тизера
cropWidth Размер стороны прямоугольника, в пикселях, который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым.
cropTop Смещение от верхнего края, в пикселях, прямоугольника который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым.
cropLeft Смещение  от левого края, в пикселях, прямоугольника который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым
cropWidthQuadratic Размер стороны квадрата, в пикселях, который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым.
cropTopQuadratic Смещение от верхнего края, в пикселях, квадрата который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым.
cropLeftQuadratic Смещение  от левого края, в пикселях, квадрата который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым
whetherShowGoodPrice Флаг отображения цены товара (1/0)

При whetherShowGoodPrice = 1 параметры currency, goodPrice, goodOldPrice обязательны.
При whetherShowGoodPrice = 0  параметры будут проигнорированы.

currency Идентификатор валюты для отображения цены товара
goodPrice Цена товара в указанной валюте
goodOldPrice Старая цена товара

Если какой-либо из обязательных параметров не передан, то  возвращается соответствующая ошибка, например, если не передается campaignId:

{
    "errors":    [
        "      [
         ERROR_PARAMETER_CAMPAIGNID_CAN_NOT_BE_EMPTY
      ]      "       
   ]
}

Если редактируемый тизер находится на модерации, то возвращает ошибку:

{"errors":["[ERROR_EDITING_TEASER_ON_MODERATION_NOT_PERMITTED]"]}

Изменение цены за клик для тизера рекламной кампании

Метод PATCH
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers/_идентификатор_тизера_?token=_токен_клиента_

Передаваемые параметры отправляются в body запроса:

Параметр Значение
priceOfClickByLocation Устанавливаемая цена за клик по всем гео группам в валюте клиента. В качестве разделителя можно использовать точку или запятую.
priceOfClickByLocation_{geo_zones_groups_id} Устанавливаемая цена за клик по конкретной гео группе в валюте клиента. В качестве разделителя можно использовать точку или запятую.
geo_zones_groups_id iso name geo_zones_ids parent_id
32 US USA NULL
33 US The Midwest 197,204,205,207,211,219,220,224,227,231,232,242,316 32
34 US The North-East 195,196,199,200,201,203,214,216,217,315 32
35 US The West 198,212,215,225,229,234,236,237,240,241,243,244,245,318 32
36 US The South 202,206,218,208,209,210,213,221,222,223,226,228,230,233,235,238,239,317 32
37 US Other regions 246,247,248,249,250,4 32
38 GB United Kingdom 14,282 NULL
39 AU Australia 31 NULL
40 CA Canada 13 NULL
41 NZ New Zealand 50 NULL
42 L1 Latin America NULL
43 AR Argentina 40 42
44 VE Bolivarian Republic of Venezuela 88 42
45 BR Brazil 41 42
46 CL Chile 56 42
47 CO Colombia 57 42
48 CR Costa Rica 58 42
49 DO Dominican Republic 59 42
50 EC Ecuador 60 42
51 GT Guatemala 61 42
52 MX Mexico 42 42
53 PA Panama 77 42
54 PE Peru 78 42
55 BO Plurinational State of Bolivia 55 42
56 UY Uruguay 87 42
57 L1 Other countries 266 42
58 D1 German-speaking NULL
59 AT Austria 33 58
60 BE Belgium 28 66
61 DK Denmark 38 66
62 DE Germany 5 58
63 LI Liechtenstein 72 58
64 LU Luxembourg 74 58
65 CH Switzerland 34 58
66 E1 Europe NULL
67 AL Albania 53 66
68 HR Croatia 62 66
69 CY Cyprus 46 66
70 EE Estonia 11 66
71 FI Finland 22 66
72 GR Greece 25 66
73 IS Iceland 66 66
74 IE Ireland 23 66
75 IT Italy 20 66
76 LV Latvia 9 66
77 LT Lithuania 12 66
78 MC Monaco 75 66
79 ME Montenegro 273 66
80 NL Netherlands 29 66
81 NO Norway 30 66
82 PT Portugal 32 66
83 RS Serbia 81 66
84 SI Slovenia 83 66
85 SE Sweden 26 66
86 ES Spain 17 66
87 FR France 18 66
88 E1 Other countries 267,268 66
89 Eastern Europe NULL
90 BY Belarus 8 150
91 BG Bulgaria 263 89
92 C0 Crimea 108,281,314 150
93 CZ Czech Republic 262 89
94 HU Hungary 264 89
95 PL Poland 260 89
96 RO Romania 261 89
97 MD Republic of Moldova 10 150
98 RU Russia NULL
99 SK Slovakia 265 89
100 UA Ukraine NULL
101 A3 Arabic-speaking NULL
102 EG Egypt 44 101
103 IQ Iraq 64 101
104 JO Jordan 67 101
105 KW Kuwai 70 101
106 LB Lebanon 71 101
107 SA Saudi Arabia 82 101
108 SY Syrian Arab Republic 84 101
109 AE United Arab Emirates 39 101
110 QA Qatar 80 101
111 A3 Other countries 269,283,284,285,286,287,288,289,290,291,292,293,294,295 101
112 A1 Asia NULL
113 BD Bangladesh 54 112
114 CN China 24 112
115 KH Cambodia 69 112
116 HK Hong Kong 89 112
117 IN India 47 112
118 ID Indonesia 63 112
119 JP Japan 37 112
120 MY Malaysia 48 112
121 PK Pakistan 52 112
122 PH Philippines 79 112
123 KR Republic of Korea 35 112
124 LK Sri Lanka 73 112
125 SG Singapore 90 112
126 TW Taiwan 86 112
127 TH Thailand 49 112
128 VN Viet Nam 45 112
129 A1 Other countries 270 112
130 Western Asia NULL
131 AM Armenia 27 150
132 AZ Azerbaijan 16 150
133 IR Islamic Republic of Iran 65 130
134 IL Israel 7 130
135 GE Georgia 15 130
136 KZ Kazakhstan 6 150
137 KG Kyrgyzstan 36 150
138 TJ Tajikistan 43 150
139 TR Turkey 19 130
140 TM Turkmenistan 85 150
141 UZ Uzbekistan 21 150
143 A2 Africa NULL
144 KE Kenya 68 143
145 NG Nigeria 76 143
146 ZA South Africa 51 143
147 A2 Other countries 272 143
148 O1 Other countries 0,1 NULL
150 S1 CIS countries NULL
151 RU Far Eastern Federal District 168,124,278,258,183,137,93,127,274,111,188,300 98
152 RU Ural Federal District 155,123,121,115,104,169,301 98
153 RU Siberian Federal District 122,153,185,259,131,132,100,257,113,92,277,147,177,275,171,276,279,280,302 98
154 RU Southern Federal District 164,187,96,184,129,135,304 98
155 RU Northwestern Federal District 140,119,101,166,141,142,167,145,159,305 98
156 RU Central Federal District 181,161,146,106,125,109,163,174,143,134,162,95,126,144,139,103,306 98
157 RU North Caucasian Federal District 170,255,186,194,151,117,254,307 98
158 RU Moscow 94,251,308 98
159 RU Saint Petersburg 102,252,309 98
160 RU Other regions 3 98
161 UA Northern Ukraine 100
162 UA Central Ukraine 100
163 UA Southern Ukraine 100
164 UA Western Ukraine 100
165 UA Eastern Ukraine 100
166 UA Kyiv 112,253,313 100
167 UA Other regions 2 100
168 UA Donetsk 116 165
169 UA Lugansk 172 165
170 UA Kharkov 105 165
171 UA Volhynia 157 164
172 UA Zakarpattia Oblast 158 164
173 UA Ivano-Frankivsk 192,312 164
174 UA Lviv 193 164
175 UA Rivne 191 164
176 UA Ternopil 133 164
177 UA Khmelnytskyi 179 164
178 UA Chernivtsi 156 164
179 UA Zhytomyr 128,31 161
180 UA Sumy 175 161
181 UA Chernihiv 176 161
182 UA Vinnytsia 190,311 162
183 UA Dnipro 150 162
184 UA Kropyvnytskyi 160 162
185 UA Poltava 189 162
186 UA Cherkasy 178 162
187 UA Zaporizhia 173 163
188 UA Mykolaiv 182 163
189 UA Odessa 97 163
190 UA Kherson 99 163
191 RU Volga Federal District 152,180,118,165,138,136,154,107,114,256,130,98,120,149,110,148,303 98

Возвращаемый ответ:

При успешном изменении цены за клик  возвращается ответ:

{     
  "id":_идентификатор_тизера_,  
}

Ошибки выводятся в следующих случаях:

  • если параметр цены за клик не указан или указан не верно
{"errors":["[EDIT_PRICE_REQUIRED_PRICES]"]}
  • если цена не указана или указано не валидное значение
{"errors":["[VALIDATION_NOT_FLOAT]","[VALIDATION_NOT_FLOAT]"]}
  • если цена указана ниже минимальной
{"errors":["The price is not valid"]}
  • если цена указана выше максимальной
    {"errors":["[LS_CAB_'51'_MORE_THAN_'50']","[LS_CAB_'51'_MORE_THAN_'50']"]}

Блокировка / разблокировка тизера для рекламной кампании

Метод PATCH
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers/_идентификатор_тизера_?token=_токен_клиента_

Передаваемые параметры отправляются в body запроса:

Параметр Значение
whetherToBlockByClient 1 —  блокирует  тизер

0 —  разблокирует тизер

Возвращаемый ответ

Если операция выполнена успешна, то возвращается идентификатор тизера, для которого была изменено состояние:

{"id":"_идентификатор_тизера_"}

Удаление тизера (перемещение в корзину) для рекламной кампании

Метод DELETE
URL api.mgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers/_идентификатор_тизера_?token=_токен_клиента_

Передаваемые параметры отсутствуют.

Возвращаемый ответ:

Если операция выполнена успешно, то возвращается идентификатор тизера,  который  был  перемещен в корзину:

{"id":"_идентификатор_тизера_"}

Если тизер с указанным идентификатором отсутствует в системе или уже был перемещен в корзину, то будет возвращено сообщение:

[ERROR_RESOURCE_NOT_FOUND]