Баннеры

Баннер - это JSON-документ, параметризующий шаблон. Баннер должен определять все переменные, обьявленные в шаблоне.

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

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

Создание баннера

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

Поле Описание Обязателен Разрешенные значения
campaign Id кампании Нет
Id существующей кампании
Целое число
template Id шаблона Да
Целое число
size Id размера Да
Целое число
variables
JSON-документ с
переменными
шаблона
Да
Определяется шаблоном
click_url URL для перехода Да
Любой URL
“^https?://([\da-z\.-]+)\.([a-z\.]{2,6})([/\w\.-]*)*([/?].*)?$”
description Описание Нет
UTF8-текст.
Длина: < 400 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{0,10000}$”
is_valid Статус модерации Нет true, false
invalid_reason text Причина непрохождения модерации Нет Текст

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

Обратите внимание, что при создании баннера необходимо указать идентификатор существующего шаблона в поле template. В примерах мы будем полагать, что в системе уже существует шаблон template1 c телом "Hello {{name}}!".

Только модераторы и администраторы могут изменять поля is_valid и invalid_reason text.

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "campaign":1,
          "template":1,
          "size":1,
          "variables": {
            "name":"alice"
          },
          "click_url":"http://example.com",
          "description":"This is your banner"
        }' \
       --url http://api.example.com/banners

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Thu, 14 Nov 2013 08:19:32 GMT
Content-Type: application/json
Content-Length: 142
Connection: keep-alive
Location: http://api.example.com/banners/3

{
  "id":1,
  "campaign":1,
  "template":1,
  "size":1,
  "variables": {
    "name":"alice"
  },
  "click_url":"http://example.com",
  "description":"This is your banner",
  "is_valid":null,
  "invalid_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
}

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

Только пользователям с ролью advertiser и администраторам разрешено создавать баннеры. Если, указано поле campaign, то баннер будет создан только в том случае, если пользователь является сотрудником организации, к-й принадлежит данная кампания.

Поиск баннеров

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

Пример:

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

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Thu, 14 Nov 2013 08:21:30 GMT
Content-Type: application/json
Content-Length: 156
Connection: keep-alive

{
  "results": [
    {
      "id":1,
      "campaign":1,
      "template":1,
      "size":1,
      "variables": {
        "name": "alice"
      },
      "click_url":"http://example.com",
      "description":"This is your banner",
      "is_valid":null,
      "invalid_reason":null,
      "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 /banners/moderation.

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/banners/moderation

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Thu, 14 Nov 2013 08:21:30 GMT
Content-Type: application/json
Content-Length: 156
Connection: keep-alive

{
  "results": [
    {
      "id":1,
      "campaign":1,
      "template":1,
      "size":1,
      "variables": {
        "name": "alice"
      },
      "click_url":"http://example.com",
      "description":"This is your banner",
      "is_valid":null,
      "invalid_reason":null,
      "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 и moderator могут получить список баннеров на модерации.

Чтобы пометить баннер как прошедший модерацию, установите поле is_valid в true. Чтобы пометить баннер как непрошедший валидацию установите поле is_valid в false, а в поле invalid_reason укажите причину непрохождения модерации.

Получение данных баннера

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

Пример:

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

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Thu, 14 Nov 2013 08:25:05 GMT
Content-Type: application/json
Content-Length: 142
Connection: keep-alive
Location: http://api.example.com/banners/1

{
  "id":1,
  "campaign":1,
  "template":1,
  "size":1,
  "variables": {
    "name":"alice"
  },
  "click_url":"http://example.com",
  "description":"This is your banner",
  "is_valid":null,
  "invalid_reason":null,
  "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
}

Превью баннера

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

Пример:

$ curl --request GET \
       --include \
       --user admin:admin \
       --url http://api.example.com/banners/1/preview

HTTP/1.1 200 OK
Server: nginx/1.4.4
Date: Tue, 17 Dec 2013 07:21:30 GMT
Content-Type: text/html
Content-Length: 13
Connection: keep-alive

Hello, alice!

Изменение данных баннера

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

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

Пример:

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

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Thu, 14 Nov 2013 08:47:19 GMT
Content-Type: application/json
Content-Length: 140
Connection: keep-alive

{
  "id":1,
  "campaign":1,
  "template":1,
  "size":1,
  "variables": {
    "name":"alice"
  },
  "click_url":"http://example.com",
  "description":"My awesome banner",
  "is_valid":null,
  "invalid_reason":null,
  "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
}

Удаление баннера

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

Пример:

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

HTTP/1.1 204 No Content
Server: nginx/1.4.3
Date: Thu, 14 Nov 2013 08:49:02 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive

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

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

GET /banners/: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/banners/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/banners/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 /banners/:id/stats

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/banners/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
}