Работа с пользовательскими таргетингами

Добавление нового пользовательского таргетинга для сайта
Добавление нового пользовательского таргетинга для пользователя
Добавление связи между пользовательским таргетингом и сайтом данного пользователя
Удаление связи между пользовательским таргетингом и сайтом данного пользователя
Получение списка пользовательских таргетингов данного сайта пользователя
Получение списка всех пользовательских таргетингов данного пользователя
Редактирование данных пользовательского таргетинга
Просмотр данных пользовательского таргетинга
Получение статистики по значениям пользовательского таргетинга для сайта

Использование программного интерфейса позволяет осуществлять следующие операции с пользовательскими таргетингами в системе AdRiver:

добавление нового пользовательского таргетинга;
просмотр списка всех пользовательских таргетингов;
изменение пользовательского таргетинга;
просмотр данных пользовательского таргетинга.

При работе с пользовательскими таргетингами в системе AdRiver через программный интерфейс используются следующие параметры:

system

статус пользовательского таргетинга (системный – 1, обычный — 0)

protected

признак защищенности таргетинга (защищенный – 1, незащищенный — 0), следует обратить внимание на то, что установка значения 1 запретит любые изменения в данном пользовательском таргетинге, включая запрет на его удаление; поэтому рекомендуется использовать только значение 0

name

наименование пользовательского таргетинга

position

номер позиции в запросе (от 1 до 99)

value_type

тип значения таргетинга (символьный — ‘string’ или целочисленный — ‘int_range’)

идентификатор таргетинга

values

массив возможных значений таргетинга

Более подробную информацию о добавлении и настройке пользовательских таргетингов можно получить из документации на сайте.

1. Добавление нового пользовательского таргетинга для сайта

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

Примечание: При работе с пользовательскими таргетингами в системе AdRiver через программный интерфейс следует использовать формат application/json.

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

POST/users/179221/sites/179042/custom_targetings
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%3E

{
  "type": "Targeting::Custom",
  "system" : 0,
  "protected" : 0,
  "position" : "1",
  "name" : "Образование",
  "value_type": "string",
  "values" : 
  [
    {
      "type" : "Targeting::Custom::Value::String",
      "name" : "высшее",
      "string": "high"
    },
    {
      "type" : "Targeting::Custom::Value::String",
      "name" : "без образования",
      "string": "none"
    }
    {
      "type" : "Targeting::Custom::Value::String",
      "name" : "среднее",
      "string": "secondary"
    }
  ],
}

Примечания к коду:

179042 — Идентификатор сайта, для которого добавляется таргетинг.

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

{
       "system" : "0",
       "protected" : "0",
       "name" : "Образование",
       "position" : "1",
       "values" : 
       [
          {
             "name" : "высшее",
             "type" : "Targeting::Custom::Value::String",
             "string" : "high"
          },
          {
             "name" : "без образования",
             "type" : "Targeting::Custom::Value::String",
             "string" : "none"
          }
          {
             "name" : "среднее",
             "type" : "Targeting::Custom::Value::String",
             "string" : "secondary"
          }
       ],
       "value_type" : "string",
       "type" : "Targeting::Custom",
       "id" : "3FC4435C-BF87-11E1-BF8E-8DFAF5422389",
}

Примечания к коду:

«system» : «0» — Добавленный таргетинг не системный.
Образование — Название добавленного таргетинга.
«values» — Массив значений добавленного таргетинга.
3FC4435C-BF87-11E1-BF8E-8DFAF5422389 — Идентификатор добавленного таргетинга.

Код ответа 201.

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

{
  "error":"Bad login or password",
  "type":"Adriver::RestAPI::Exception::UnAuthorized"
}

Код ответа 401.

Также ошибка выдается при попытке добавления пользовательского таргетинга для несуществующего сайта:

{
"error":"Site (id 1788623) not found.",
"type":"Adriver::RestAPI::Targeting::Custom::Exception::SiteNotFound"
}

Код ответа 401.

2. Добавление нового пользовательского таргетинга для пользователя

Имеется также возможность добавления пользовательского таргетинга для пользователя. Такой таргетинг в дальнейшем может быть связан с несколькими сайтами этого пользователя с помощью соответствующего запроса (см. п.3). Пример запроса на добавление пользовательского таргетинга с целочисленными значениями для пользователя:

POST/users/179221/custom_targetings
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%3E

{
  "type": "Targeting::Custom",
  "system": "0",
  "protected": "0",
  "position": 1,
  "name": "ID пользователя",
  "value_type": "int_range",
  "values": 
  [
    {
      "type": "Targeting::Custom::Value::IntRange",
      "name": "1-3",
      "min": 1,
      "max": 3
    },
    {
      "type": "Targeting::Custom::Value::IntRange",
      "name": "4-6",
      "min": 4,
      "max": 6
    },
    {
      "type": "Targeting::Custom::Value::IntRange",
      "name": "8-10",
      "min": 8,
      "max": 10
    }
  ]
}

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

{
  "system":"0",
  "protected":"0",
  "name":"ID пользователя",
  "position":1,
  "values":
  [
    {
      "min":1,
      "name":"1-3",
      "max":3,
      "type":"Targeting::Custom::Value::IntRange"
    },
    {
      "min":4,
      "name":"4-6",
      "max":6,
      "type":"Targeting::Custom::Value::IntRange"
    },
    {
      "min":8,
      "name":"8-10",
      "max":10,
      "type":"Targeting::Custom::Value::IntRange"
    }
  ],
  "value_type":"int_range",
  "id":"99DAD784-D00D-11E1-84F7-EB9DFDA2427D",
  "type":"Targeting::Custom"
}

Примечания к коду:

«system» : «0» — Добавленный таргетинг не системный.
ID пользователя — Название добавленного таргетинга.
«values» — Массив значений добавленного таргетинга.
99DAD784-D00D-11E1-84F7-EB9DFDA2427D— Идентификатор добавленного таргетинга.

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

{
  "error":"Cannot bind targeting E33CBFDC-D00D-11E1-A933-EB9DFDA2427D to site 178863. User's targeting 99DAD784-D00D-11E1-84F7-EB9DFDA2427D with same position exists",
  "type":"Adriver::RestAPI::Targeting::Custom::Exception::TargetingConflict"
}

3. Добавление связи между пользовательским таргетингом и сайтом данного пользователя

Для добавления связи между созданным ранее таргетингом для пользователя (см. п.2.) и сайтом этого пользователя следует выполнить следующий запрос:

POST/users/179221/sites/178863/custom_targetings/bind
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%3E

{
  "items": ["F0254572-D254-11E1-BB33-B9ADEC20ED3D"]
}

Примечания к коду:

178863 — Идентификатор сайта, с которым связывается таргетинг.
F0254572-D254-11E1-BB33-B9ADEC20ED3D — Идентификатор пользовательского таргетинга для связи с сайтом.

В случае успешного создания связи между пользовательским таргетингом и сайтом выдается ответ вида:

201 
{}

4. Удаление связи между пользовательским таргетингом и сайтом данного пользователя

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

DELETE/users/179221/sites/178863/custom_targetings/529AA134-D011-11E1-A933-EB9DFDA2427D
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%3E

Код ответа 204.

5. Получение списка пользовательских таргетингов данного сайта пользователя

Нижеследующий запрос позволяет получить список всех пользовательских таргетингов данного сайта (в примере – сайта 178863).

GET/users/179221/sites/178863/custom_targetings/
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%4E

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

{
  "items":
  [
    {
      "system":"0",
      "protected":"0",
      "name":"ID пользователя",
      "position":1,
      "values":
      [
        {
          "min":"1",
          "name":"1-3",
          "max":"3",
          "type":"Targeting::Custom::Value::IntRange"
        },
        {
          "min":"4",
          "name":"4-6",
          "max":"6",
          "type":"Targeting::Custom::Value::IntRange"
        },
        {
          "min":"8",
          "name":"8-10",
          "max":"10",
          "type":"Targeting::Custom::Value::IntRange"
        }
      ],
      "value_type":"int_range",
      "type":"Targeting::Custom",
      "id":"F0254572-D254-11E1-BB33-B9ADEC20ED3D",
      "owner_id":179221
    },
    {
      "system":"1",
      "protected":"1",
      "name":"Пол",
      "position":"100",
      "values":
      [
        {
          "name":"женский",
          "type":"Targeting::Custom::Value::String",
          "string":"f"
        },
        {
          "name":"мужской",
          "type":"Targeting::Custom::Value::String",
          "string":"m"
        }
      ],
      "value_type":"string",
      "type":"Targeting::Custom",
      "id":"1ED63174-C19A-11DF-8D53-C44BEAD1786B",
      "owner_id":2
    },
    {
      "system":"1",
      "protected":"1",
      "name":"Возраст",
      "position":"101",
      "values":
      [],
      "value_type":"int_range",
      "type":"Targeting::Custom",
      "id":"1EDC16E8-C19A-11DF-8D53-C44BEAD1786B",
      "owner_id":2
    }
  ]
}

Примечания к коду:

F0254572-D254-11E1-BB33-B9ADEC20ED3D — Идентификатор первого пользовательского таргетинга сайта.
1ED63174-C19A-11DF-8D53-C44BEAD1786B— Идентификатор второго пользовательского таргетинга сайта.
1EDC16E8-C19A-11DF-8D53-C44BEAD1786B— Идентификатор третьего пользовательского таргетинга сайта.

Код ответа 200.

6. Получение списка всех пользовательских таргетингов данного пользователя

Нижеследующий запрос позволяет получить список всех пользовательских таргетингов данного пользователя (в примере – пользователя 179221).

GET/users/179221/ custom_targetings/
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%4E

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

{
  "items":
    {
      "system":"0",
      "protected":"0",
      "name":"Категории",
      "position":1,
      "values":
      [
        {
          "name":"Clips",
          "type":"Targeting::Custom::Value::String",
          "string":"Clips"
        },
        {
          "name":"Films",
          "type":"Targeting::Custom::Value::String",
          "string":"Films"
        },
        {
          "name":"Music",
          "type":"Targeting::Custom::Value::String",
          "string":"Music"
        }
      ],
      "value_type":"string",
      "type":"Targeting::Custom",
      "id":"10F0882E-BF87-11E1-8A15-8DFAF5422389",
      "owner_id":179221
    },
    {
      "system":"0",
      "protected":"0",
      "name":"Размер предприятия",
      "position":1,
      "values":
      [
        {
          "min":"5",
          "name":"5-15",
          "max":"15",
          "type":"Targeting::Custom::Value::IntRange"
        },
        {
          "min":"16",
          "name":"16-50",
          "max":"50",
          "type":"Targeting::Custom::Value::IntRange"
        },
        {
          "min":"51",
          "name":"51-100",
          "max":"100",
          "type":"Targeting::Custom::Value::IntRange"
        }
      ],
      "value_type":"int_range",
      "type":"Targeting::Custom",
      "id":"99DAD784-D00D-11E1-84F7-EB9DFDA2427D",
      "owner_id":179221
    },
    {
      "system":"0",
      "protected":"0",
      "name":"Образование",
      "position":"1",
      "values":
      [
        {
          "name":"высшее",
          "type":"Targeting::Custom::Value::String",
          "string":"high"
        },
        {
          "name":"без образования",
          "type":"Targeting::Custom::Value::String",
          "string":"none"
        },
        {
          "name":"среднее",
          "type":"Targeting::Custom::Value::String",
          "string":"secondary"
        }
      ],
      "value_type":"int_range",
      "type":"Targeting::Custom",
      "id":"F0254572-D254-11E1-BB33-B9ADEC20ED3D",
      "owner_id":179221
    },
  ]
}

7. Редактирование данных пользовательского таргетинга

Если необходимо изменить данные ранее добавленного пользовательского таргетинга в системе AdRiver, то это можно осуществить с помощью запроса на его изменение. Операция редактирования по своей сути аналогична операции добавления пользовательского таргетинга, поскольку в соответствующем запросе содержится полный список параметров изменяемого пользовательского таргетинга.

PUT/users/178072/custom_targetings/3FC4435C-BF87-11E1-BF8E-8DFAF5422389
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%4E

{
  "type": "Targeting::Custom", 
  "system": "0", 
  "protected": "0", 
  "position": 2, 
  "name": "Размер предприятия", 
  "value_type": 
  "int_range", 
  "id": "3FC4435C-BF87-11E1-BF8E-8DFAF5422389", 
  "values": 
  [
    {
      "type": "Targeting::Custom::Value::IntRange", 
      "name": "5-15", 
      "min": 5, 
      "max": 15
    }, 
    {
      "type": "Targeting::Custom::Value::IntRange", 
      "name": "16-50", 
      "min": 16, 
      "max": 50
    }, 
    {
      "type": "Targeting::Custom::Value::IntRange", 
      "name": "51-100", 
      "min": 51, 
      "max": 100
    }, 
    {
      "type": "Targeting::Custom::Value::IntRange", 
      "name": "101-300", 
      "min": 101, 
      "max": 300
     }
  ]
}

Примечания к коду:

3FC4435C-BF87-11E1-BF8E-8DFAF5422389 — Идентификатор пользовательского таргетинга для редактирования.

В случае успешного редактирования в ответе возвращаются все текущие данные пользовательского таргетинга.

{
  "system":"0",
  "protected":"0",
  "name":"Размер предприятия",
  "position":2,
  "values":
  [
    {
      "min":5,
      "name":"5-15",
      "max":15,
      "type":"Targeting::Custom::Value::IntRange"
    },
    {
      "min":16,
      "name":"16-50",
      "max":50,
      "type":"Targeting::Custom::Value::IntRange"
    },
    {
      "min":51,
      "name":"51-100",
      "max":100,
      "type":"Targeting::Custom::Value::IntRange"
    },
    {
      "min":101,
      "name":"101-300",
      "max":300,
      "type":"Targeting::Custom::Value::IntRange"
    }
    {
      "min":301,
      "name":"301-500",
      "max":500,
      "type":"Targeting::Custom::Value::IntRange"
    }
  ],
  "value_type":"int_range",
  "id":"67E3150C-D00D-11E1-84F7-EB9DFDA2427D",
  "type":"Targeting::Custom"
}

Код ответа 200.

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

{
  "error":"Targeting with id=3FC4435C-BF87-11E1-BF8E-8DFAF5422388 not found in DB",
  "type":"Adriver::RestAPI::Targeting::Custom::Exception::TargetingNotFound
}

Код ответа 404.

8. Просмотр данных пользовательского таргетинга

Имеется возможность также получить данные пользовательского таргетинга по его уникальному идентификатору (id). Идентификатор пользовательского таргетинга выдается в ответе системы при его добавлении, также можно получить идентификаторы всех пользовательских таргетингов данной учетной записи при просмотре списка пользовательских таргетингов пользователя (см. п.6).

Пример запроса на просмотр данных пользовательского таргетинга:

GET/users/179022/custom_targetings/3FC4435C-BF87-11E1-BF8E-8DFAF5422389
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%4E

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

{
  "system":"0",
  "protected":"0",
  "name":"Образование",
  "position":"1",
  "values":
  [
    {
      "name":"высшее",
      "type":"Targeting::Custom::Value::String",
      "string":"high"
    },
    {
      "name":"без образования",
      "type":"Targeting::Custom::Value::String",
      "string":"none"
    },
    {
      "name":"среднее",
      "type":"Targeting::Custom::Value::String",
      "string":"secondary"
    },
  ],
  "value_type":"string",
  "type":"Targeting::Custom",
  "id":"3FC4435C-BF87-11E1-BF8E-8DFAF5422389",
  "owner_id":179221
}

В случае ошибки, например, если запрос на просмотр данных пользовательского таргетинга включает в себя идентификатор недопустимого формата (с синтаксической ошибкой), выдается ответ следующего вида:

{
"error":""3FC14435C-BF87-11E1-BF8E-8DFAF5422388" is not a valid GUID string at /usr/local/rle/lib/perl5/Adriver/MooseX/Types/GUID.pm line 14n",
"type":"Adriver::RestAPI::Targeting::Custom::Exception"
}

Код ответа 500.

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

С помощью программного интерфейса можно получить статистические данные по значениям пользовательского таргетинга для сайта. Соответствующие запросы позволяют получить статистику по следующим показателям:

показы;
клики;
программные события (действия пользователя по отношению к баннеру, вызывающие обращения к серверу, например, наведение курсора мыши, перемещение внутри баннера и т.п.).

Статистика может быть запрошена по заданному временному периоду. Период получения статистических данных задается с помощью указания даты начала и даты окончания периода.

Примечание: При указании периода получения статистики необходимо иметь в виду, что ненулевые статистические данные могут быть получены только за период реального выполнения рекламных кампаний на сайте. Срок хранения статистической информации системы для сайтов, рекламных кампаний, сценариев и баннеров составляет 365 суток.

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

start_date

дата начала периода получения статистики в формате YYYY-MM-DD

stop_date

дата окончания периода получения статистики в формате YYYY-MM-DD

stop_date

дата окончания периода получения статистики в формате YYYY-MM-DD

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

sort_by

о какому полю (показы (exp) или клики (click)) сортировать информацию при выводе

limit

ограничение на количество значений таргетинга при выводе

desc

порядок сортировки (1 – по уменьшению, 0 – по увеличению)

Пример запроса на получение статистических данных пользовательского таргетинга:

GET /users/165773/sites/168077/custom_targetings/2FF87E06-2D35-11E0-99B5-A13469A66108/stat?start_date=2011-01-01T00:00:00&stop_date=2011-01-31T00:00:00&sort_by=exp&limit=100desc=1
Content-Type:application/json
X-Auth-UserID:179221
X-Auth-Passwd:v%CB%0FYt%1Bv%A6%A0%BD%99%4E

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

{
  "system" : "0",
  "protected" : "0",
  "name" : "Образование",
  "position" : "1",
  "values" : [
    {
      "exp" : 23198,
      "clk" : 0,
      "type" : "Targeting::Custom::Stat::Value::String",
      "string" : "high",
      "subevents" : [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    },
    {
      "exp" : 8459,
      "clk" : 0,
      "type" : "Targeting::Custom::Stat::Value::String",
      "string" : "none",
      "subevents" : [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
    {
      "exp" : 3530,
      "clk" : 0,
      "type" : "Targeting::Custom::Stat::Value::String",
      "string" : "secondary",
      "subevents" : 
      [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
  ],
  "stop_date" : "2011-01-31T00:00:00",
  "value_type" : "string",
  "stat_period" : [
    "2011-01-01T00:00:00",
    "2011-01-31T00:00:00"
  ],
  "type" : "Targeting::Custom::Stat",
  "id" : "2FF87E06-2D35-11E0-99B5-A13469A66108",
  "owner_id" : 179221,
  "start_date" : "2011-01-01T00:00:00"
}

Примечания к коду:

«exp» : 23198, «clk» : 0 — Количество показов и кликов посетителей, соответствующих данному значению таргетинга.
«exp» : 8459, «clk» : 0 — Количество показов и кликов посетителей, соответствующих данному значению таргетинга.
«exp» : 3530, «clk» : 0 — Количество показов и кликов посетителей, соответствующих данному значению таргетинга.