Рекламные кампании

Управление кампаниями осуществляется с помощью двух ресурсов:

  • /campaigns - ресурс для управления коллекцией кампаний
  • /campaign/:id - ресурс для управления конкретной кампанией с идентификатом :id
Метод Ресурс Результат
POST /campaigns создать кампанию
GET /campaigns найти кампании
GET /campaigns/:id получить данные кампании
POST /campaigns/:id изменить данные кампании
DELETE /campaigns/:id удалить кампанию

Необязательный параметр set_tz содержит таймзону в к-й должно отображаться время:

GET /campaigns?set_tz=03:00
GET /campaigns?set_tz=-03:00

Создание кампании

Чтобы создать кампанию, необходимо выполнить запрос POST /campaigns с JSON-документом в теле вида:

Поле Описание Обязателен Разрешенные значения
name Название кампании Да
UTF8-текст
Длина: 3-150 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{3,150}$”
description Описание Нет
UTF8-текст.
Длина: 0-400 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{0,10000}$”
enabled Вкл/выкл Нет
true - включить кампанию
false - выключить кампанию
start_time Время начала работы кампании Да
Время в формате ISO 8601 (см. Введение).
stop_time Время окончания работы кампании Нет
Время в формате ISO 8601 (см. Введение).
shows Кол-во показов Нет
Положительное число
unique_shows Кол-во уникальных показов Нет
Положительное число
clicks Кол-во кликов Нет
Положительное число
unique_clicks Кол-во уникальных кликов Нет
Положительное число
shows_per_day Кол-во кликов в день Нет
Положительное число
clicks_per_day Кол-во кликов в день Нет
Положительное число
unique_shows_per_day Кол-во уникальных кликов в день Нет
Положительное число
unique_clicks_per_day Кол-во уникальных кликов в день Нет
Положительное число
shows_per_unique_user
Кол-во показов
уникальному
пользователю
Нет
Положительное число
targeting Параметры таргетинга Нет
См. ниже
mode Режим показов Нет
null, “free”, “max”
company Id организации Да
Id существующей организации
“^[-\w]{3,20}$”
tz Таймзона Нет
Строка в формате ±HH:MM

Каждая кампаиня имеет уникальный id, генерируемый сервером при создании. Ссылка на созданный баннер возвращается сервером в заголовке Location.

Обратите внимание, что при создании кампании необходимо указать идентификатор существующей площадки в поле site. В примерах мы будем полагать, что в системе уже существует площадка c идентификатором example.com.

В случае если shows, clicks, unique_shows, unique_clicks и mode не указаны, кампания переводится в режим свободных показов.

Поле targeting может содержать документ вида:

Поле Описание Обязателен Разрешенные значения
sites Список Id площадок Нет
Список id вида ‘example.com’
Длина каждого id: 3-100 символов.
“^[-\w\.]{3,100}$”
sites_mode Режим работы таргетинга на площадки Нет
“allow”, “deny”
slots Список Id слотов Нет Список целых чисел - id слотов
browser Браузер Нет chrome, msie, firefox, safari, opera
os Операционная система Нет windows, osx, linux, android, ios
device Устройство Нет iphone, ipad, ipod
device_type Тип устройства Нет desktop, mobile
countries Список Id стран Нет
Список Id стран
Идентификаторы стран: countries.json
cities Список Id городов Нет
Список Id городов
Идентификаторы городов: cities.json
cities_mode Режим работы таргетинга на города Нет
“allow”, “deny”
url_regexp Шаблон url Нет Строка, регулярное выражение

Read-only поле active содержит текущий статус кампании: true - кампания находится в ротации, false - кампания не включена в ротацию. Если по какой-либо причине кампания не попадает в ротацию, то поле в stop_reason указывается причина.

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

Значение stop_reason Описание
not_enabled Кампания не включена
not_enough_funds Недостаточно средств на одном из счетов
start_time_not_reached Время начала кампании еще не наступило
stop_time_reached Срок действия кампании истек
shows_reached Общее кол-во показов превышено
unique_shows_reached Общее кол-во уникальных показов превышено
clicks_reached Общее кол-во кликов превышено
unique_clicks_reached Общее кол-во уникальных кликов превышено
shows_per_day_reached Кол-во показов в сутки превышено
unique_shows_per_day_reached Кол-во уникальных показов в сутки превышено
clicks_per_day_reached Кол-во кликов в сутки превышено
unique_clicks_per_day_reached Кол-во уникальных кликов в сутки превышено

Поле mode устанавливает режим показов:

“free” режим свободных показов
“max” режим максимальных показов

Пример:

$ curl --request POST \
     --include \
     --user "admin:admin" \
     --header "Content-Type: application/json" \
     --data \
     '{
        "name":"Campaign name",
        "enabled":true,
        "start_time":"2013-12-10T01:02:03+03",
        "stop_time":"2013-12-11T01:02:03+03",
        "shows":1000,
        "unique_shows":null,
        "clicks":1000,
        "unique_clicks":null,
        "shows_per_day":10,
        "clicks_per_day":10,
        "unique_shows_per_day":10,
        "unique_clicks_per_day":10,
        "targeting": {
          "sites":["example.com"],
          "browser": "chrome",
          "os": "linux",
          "device_type": "desktop",
          "countries": ["RU"],
          "cities": ["2097"]
        },
        "company":"example",
        "description":"Test campaign"
      }' \
     --url http://api.example.com/campaigns

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Wed, 13 Nov 2013 10:18:14 GMT
Content-Type: application/json
Content-Length: 303
Connection: keep-alive
Location: http://api.example.com/campaigns/1

{
  "id":1,
  "name":"Campaign name",
  "description":"Test campaign",
  "enabled":true,
  "active":true,
  "stop_reason":null,
  "start_time":"2013-12-10T01:02:03+03",
  "stop_time":"2013-12-11T01:02:03+03",
  "shows":1000,
  "unique_shows":null,
  "clicks":1000,
  "unique_clicks":null,
  "shows_per_day":10,
  "clicks_per_day":10,
  "unique_shows_per_day":10,
  "unique_clicks_per_day":10,
  "targeting": {
     "sites":["example.com"],
     "browser": "chrome",
     "os": "linux",
     "device_type": "desktop",
     "countries": ["RU"],
     "cities": ["2097"]
    },
  "company":"example",
  "shows_today":0,
  "ushows_today":0,
  "clicks_today":0,
  "uclicks_today":0,
  "ctr_today":0.0,
  "uctr_today":0.0,
  "shows_yesterday":0,
  "ushows_yesterday":0
  "clicks_yesterday":0,
  "uclicks_yesterday":0,
  "ctr_yesterday":0.0,
  "uctr_yesterday":0.0
}

Обратите внимание на значение заголовка Location в ответе сервера. Мы будем использовать этот URL в следующих примерах.

Только администраторы и пользователи с ролью advertiser могут создавать кампании.

Поиск кампаний

Чтобы получить список кампаний, необходимо выполнить запрос GET /campaigns.

Параметры запроса

site – кампании принадлежащие площадке

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/campaigns?set_tz=03

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Wed, 13 Nov 2013 10:22:36 GMT
Content-Type: application/json
Content-Length: 317
Connection: keep-alive

{
  "results": [
    {
      "unique_shows_per_day":10,
      "unique_clicks_per_day":10,
      "targeting": {
        "sites":["example.com"],
        "os":"linux",
        "device_type":"desktop",
        "browser":"chrome",
        "countries": ["RU"],
        "cities": ["2097"]
      },
      "start_time":"2013-12-10T01:02:03+03",
      "stop_time":"2013-12-11T01:02:03+03",
      "banners_count":0,
      "shows_per_day":10,
      "shows":1000,
      "unique_shows":null,
      "name":"Campaign name",
      "id":1,
      "description":"Test campaign",
      "clicks_per_day":10,
      "clicks":1000,
      "unique_clicks":null,
      "enabled":true,
      "active":true,
      "stop_reason":null,
      "company":"example",
      "shows_today":0,
      "ushows_today":0,
      "clicks_today":0,
      "uclicks_today":0,
      "ctr_today":0.0,
      "uctr_today":0.0,
      "shows_yesterday":0,
      "ushows_yesterday":0
      "clicks_yesterday":0,
      "uclicks_yesterday":0,
      "ctr_yesterday":0.0,
      "uctr_yesterday":0.0
    }
  ],
  "total_count": 1
}

Только пользователи с ролями administrator и advertiser могут искать кампании.

Пользователь с ролью advertiser получит только те кампании, владельцем которых является его организация.

Пользователь с ролью administrator получит все кампании.

Получение данных кампании

Чтобы получить данные кампании, необходимо выполнить запрос GET /campaigns/:id.

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/campaigns/1?set_tz=03

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Wed, 13 Nov 2013 10:24:15 GMT
Content-Type: application/json
Content-Length: 303
Connection: keep-alive

{
  "id":1,
  "name":"Campaign name",
  "description":"Test campaign",
  "enabled":true,
  "start_time":"2013-12-10T01:02:03+03",
  "stop_time":"2013-12-11T01:02:03+03",
  "banners_count":0,
  "shows":1000,
  "unique_shows":null,
  "clicks":1000,
  "unique_clicks":null,
  "shows_per_day":10,
  "clicks_per_day":10,
  "unique_shows_per_day":10,
  "unique_clicks_per_day":10,
  "targeting": {
     "sites":["example.com"],
     "browser": "chrome",
     "os": "linux",
     "device_type": "desktop",
     "countries": ["RU"],
     "cities": ["2097"]
    },
  "company":"example",
  "shows_today":0,
  "ushows_today":0,
  "clicks_today":0,
  "uclicks_today":0,
  "ctr_today":0.0,
  "uctr_today":0.0,
  "shows_yesterday":0,
  "ushows_yesterday":0
  "clicks_yesterday":0,
  "uclicks_yesterday":0,
  "ctr_yesterday":0.0,
  "uctr_yesterday":0.0
}

Изменение данных кампании

Чтобы изменить данные кампании, необходимо выполнить запрос POST /campaigns/:id.

Формат документа для обновления данных кампании идентичен формату документа для создания кампании. Если поле не указано или содержит литерал null, значение поля не будет обновлено.

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "description":"New description",
        }' \
      --url http://api.example.com/campaigns/1

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Wed, 13 Nov 2013 10:41:37 GMT
Content-Type: application/json
Content-Length: 305
Connection: keep-alive

{
  "id":1,
  "name":"Campaign name",
  "description":"New description",
  "enabled":true,
  "active":true,
  "stop_reason":null,
  "start_time":"2013-12-10T01:02:03+03",
  "stop_time":"2013-12-11T01:02:03+03",
  "shows":1000,
  "unique_shows":null,
  "clicks":1000,
  "unique_clicks":null,
  "shows_per_day":10,
  "clicks_per_day":10,
  "unique_shows_per_day":10,
  "unique_clicks_per_day":10,
  "targeting": {
     "sites":["example.com"],
     "browser": "chrome",
     "os": "linux",
     "device_type": "desktop",
     "countries": ["RU"],
     "cities": ["2097"]
    },
  "company":"example",
  "shows_today":0,
  "ushows_today":0,
  "clicks_today":0,
  "uclicks_today":0,
  "ctr_today":0.0,
  "uctr_today":0.0,
  "shows_yesterday":0,
  "ushows_yesterday":0
  "clicks_yesterday":0,
  "uclicks_yesterday":0,
  "ctr_yesterday":0.0,
  "uctr_yesterday":0.0
}

Только администраторы и пользователи с ролью advertiser в соответствующей организации могут изменять создавать кампании.

Удаление кампании

Чтобы удалить кампанию, необходимо выполнить запрос DELETE /campaigns/:id.

Пример:

$ curl --request DELETE \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/campaigns/1

HTTP/1.1 204 No Content
Server: nginx/1.4.3
Date: Wed, 13 Nov 2013 10:43:24 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive

Только администраторы и пользователи с ролью advertiser в соответствующей организации могут удалять кампании.

Получении статистики

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

GET /campaigns/:id/stats/:action/:step

Где:

id - id кампании

action - shows, ushows, clicks, uclicks

step - hour, day

Чтобы получить статистику из заданного временного интервала, укажите параметры from, to с временем в формате ISO8601.

Если параметр from не указан, то будет возвращеня статистика за 7 дней. Если параметр to не указан, то будет возвращена статистика до текущего времени.

В полях from и to следует указывать время в часовом поясе кампании.

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/campaigns/1/stats/shows/hour

HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Wed, 23 Jul 2014 06:16:57 GMT
Content-Type: application/json
Content-Length: 21
Connection: keep-alive

{
  "2014-07-23T9": 4,
  "2014-07-23T10": 5,
  "2014-07-23T11": 5
}
$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/campaigns/1/stats/ushows/day?from=2014-07-15&to=2014-07-16T10:00:00

HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Wed, 23 Jul 2014 06:16:57 GMT
Content-Type: application/json
Content-Length: 21
Connection: keep-alive

{
  "2014-07-15": 10,
  "2014-07-16": 10
}

Чтобы получить общую статистику за все время существования кампании, выполните запрос вида:

GET /campaigns/:id/stats

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/campaigns/1/stats

HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Wed, 23 Jul 2014 06:16:57 GMT
Content-Type: application/json
Content-Length: 21
Connection: keep-alive

{
  "clicks":0,
  "shows":1,
  "uclicks":0,
  "ushows":1
}