AdRiver - система управления интернет-рекламой
О компании Справочное руководство Вход в систему
Рекламным агентствам  AdRiver DSP 
Владельцам сайтов  AdRiver SSP 
Управление рекламой  AdRiver DMP 
Новости

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

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

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

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

  • system – статус пользовательского таргетинга (системный – 1, обычный - 0);
  • protected – признак защищенности таргетинга (защищенный – 1, незащищенный - 0), следует обратить внимание на то, что установка значения 1 запретит любые изменения в данном пользовательском таргетинге, включая запрет на его удаление; поэтому рекомендуется использовать только значение 0;
  • name – наименование пользовательского таргетинга;
  • position – номер позиции в запросе (от 1 до 99);
  • value_type – тип значения таргетинга (символьный - 'string' или целочисленный - 'int_range');
  • id – идентификатор таргетинга;
  • values – массив возможных значений таргетинга.

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

7.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.

Наверх

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

Имеется также возможность добавления пользовательского таргетинга для пользователя. Такой таргетинг в дальнейшем может быть связан с несколькими сайтами этого пользователя с помощью соответствующего запроса (см. п.7.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"
}

Наверх

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

Для добавления связи между созданным ранее таргетингом для пользователя (см. п.7.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 
{}

Наверх

7.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.

7.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.

Наверх

7.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.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.

Наверх

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

Имеется возможность также получить данные пользовательского таргетинга по его уникальному идентификатору (id). Идентификатор пользовательского таргетинга выдается в ответе системы при его добавлении, также можно получить идентификаторы всех пользовательских таргетингов данной учетной записи при просмотре списка пользовательских таргетингов пользователя (см. п.7.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 14\n",
"type":"Adriver::RestAPI::Targeting::Custom::Exception"
}

Код ответа 500.

Наверх

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

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

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

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

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

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

  • start_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 — Количество показов и кликов посетителей, соответствующих данному значению таргетинга.

Наверх

Последнее обновление: 26.09.2012