Требования к отображению рекламных записей

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

Для приложений с функциональностью ленты новостей метод newsfeed.get, кроме обычных записей возвращает рекламные записи — промопосты.

В вызове newsfeed.get необходимо дополнить параметр filters значением ads_post, а также передавать дополнительный параметр device_info, содержащий следующие поля:

  • •
    app_version — версия приложения;
  • •
    app_build — билд приложения;
  • •
    manufacturer — производитель, кроме iOS;
  • •
    device_model — модель устройства;
  • •
    system_name — название системы (iOS, Android);
  • •
    system_version — версия системы (6.2, 11.0.2);
  • •
    ads_device_id — ID устройства,
  • •
    ads_android_id — Android ID, только для Android;
  • •
    ads_tracking_disabled — 0, если отслеживание разрешено пользователем, 1 — запрещено.

Для пагинации ленты новостей необходимо использовать параметры start_from/next_from.

В работе с рекламными записями в ленте используйте отдельные методы для жалоб и скрытия источника из ленты: adsint.reportAd, adsint.hideAd.

Метод adsint.reportAd

Параметры:

  • •
    ad_data (string, required) — значение поля ad_data из рекламного объявления.
  • •
    reason (string) — причина жалобы. Возможные значения:
    • •
      spam — спам;
    • •
      insult — оскорбление;
    • •
      porn — материал для взрослых;
    • •
      fraud — мошенничество;
    • •
      other — другое.

Ответ: После успешного выполнения возвращает объект с полем success, которое содержит значение 1.

Метод adsint.hideAd

Параметры:

  • •
    ad_data (string, required) — значение поля ad_data из рекламного объявления.
  • •
    object_type(string`) — тип скрываемого объекта. Допустимые значения:
    • •
      ad — рекламное объявление;
    • •
      source — источник рекламного объявления. Только для промопостов.

Ответ После успешного выполнения возвращает объект с полем success, которое содержит значение 1.

Формат данных в API

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

type

string Тип записи. Всегда содержит значение ads.

ads_title

string Заголовок рекламного блока.

ads_id1

integer ID позиции в новостной ленте, часть 1.

ads_id2

integer ID позиции в новостной ленте, часть 2.

ads

array Массив рекламных объявлений, всегда содержит 1 элемент. Объект, описывающий объявление, содержит следующие поля:

  • •
    type (string) — тип объявления, всегда равен post;
  • •
    age_restriction (string) — возрастная метка;
  • •
    ad_data (string) — строка для регистрации событий методом adsint.registerAdEvents и для действий в методах adsint.hideAd и adsint.reportAd. Подробнее в разделе Регистрация событий.
  • •
    ad_data_impression — строка для регистрации событий методом adsint.registerAdEvents. Подробнее в разделе Регистрация событий.
  • •
    post (object) — объект записи на стене. В поле post_type содержится значение post_ads. Дополнительно объект может содержать поле track_code (string), необходимое для регистрации событий.
  • •
    statistics (array) — массив ссылок на пиксели для регистрации событий. Каждый объект в массиве содержит поля:
    • •
      type (string) — тип события. Возможные значения:
      • •
        load — данные об объявлении получены через API;
      • •
        impression — объявление показано пользователю;
      • •
        click_post_owner — переход по заголовку поста (в группу);
      • •
        click_post_link — переход по ссылке в посте (включая хэштег, упоминание, внутренние ссылки ВК и внешние);
    • •
      url (string) — ссылка на пиксель, возможно с промежуточными редиректами.

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

  • •
    В методах секции likes рекламные записи задаются типом объекта post_ads.
  • •
    В методе wall.getById в поле type для рекламных записей возвращается значение post_ads. Кроме того, в этот метод всегда нужно передавать параметр track_code при его наличии.
  • •
    В методе wall.repost для рекламной записи необходимо указывать префикс wall_ads.
  • •
    В методах секции messages в поле attachment рекламной записи соответствует тип wall_ads.

Оформление рекламной записи

Рекламная запись должна быть показана в ленте на той же позиции, на которой она находится в ответе от метода newsfeed.get. Для рекламной записи необходимо использовать стандартное оформление блоков в ленте с добавлением заголовка (поле ads_title) и возрастного ограничения (age_restriction) в верхней части блока. Например:

Регистрация событий

Необходимо отправлять данные о взаимодействии пользователя с рекламной записью — как из ленты новостей, так и при открытии рекламной записи на отдельном экране. Для этого используются три механизма (в каждом случае необходимо использовать все три).

Пиксели статистики

В поле statistics объекта, описывающего объявление, возвращаются данные пикселей статистики. Каждый объект, описывающий пиксель, содержит название события в поле type (string) (например, переход к владельцу рекламной записи или показ рекламной записи) и URL пикселя, который соответствует этому событию, в поле url (string).

Как только произошло событие с типом type, необходимо открыть URL из соответствующего поля url. Каждый тип события может встречаться несколько раз с разными ссылками. При наступлении события нужно загружать все пиксели этого типа, при этом каждая ссылка должна загружаться не более одного раза для событий load и impression. Для проверки на уникальность события необходимо хранить ключ вида <type>:<ads_id1>:<ads_id2> не менее суток (или хранить не менее 1000 последних ключей), и перед отправкой события проверять наличие соответствующего ключа в хранилище.

Внимание!

URL пикселя может содержать цепочку редиректов. Необходимо корректно обрабатывать файлы cookies в соответствии с заголовками HTTP-ответов.

adsint.registerAdEvents

В момент показа рекламной записи необходимо вызвать метод adsint.registerAdEvents с параметром events (array) в таком формате:

JSON
[{ "event_type": "impression", "ad_data_impression": "ZDI0MWVl" }, {...}]

Каждый элемент массива events — объект, который содержит два поля:

  • •
    event_type (string) — всегда должен содержать значение impression;
  • •
    ad_data_impression (string) — значение одноименного поля из объекта рекламной записи.

Внимание!

Метод adsint.registerAdEvents нужно вызвать не позднее, чем в течение 5 секунд после того, как произошло событие.

stats.trackEvents

В момент показа или действия рекламной записью необходимо вызвать метод stats.trackEvents с параметром events (array) в таком формате:

JSON
[{ "e":"view_post", "post_ids":["123_456", ...], "track_code":["sdfsdf", ..] }, {...}]

Каждый элемент массива events — объект, описывающий событие. Набор полей в нём зависит от типа события.

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

Объект, описывающий событие, содержит поля:

e

string Тип события. Всегда содержит значение view_post.

post_ids

(array) Данные о просмотренных записях. Каждый элемент массива представляет собой строку вида <owner_id>_<post_id>. Здесь owner_id — идентификатор владельца записи, post_id — идентификатор записи.

track_code

(array) Значение поля track_code из объекта записи. Элементы массива track_code должны поиндексно соответствовать элементам массива post_ids.

repost_ids

(array) Данные об оригиналах просмотренных записей, если они являются репостами (только предыдущий пост в цепочке, репостом которого является рекламная запись). Формат аналогичен полю post_ids, элементы массива repost_ids должны поиндексно соответствовать элементам массива post_ids.

Действие с рекламной записью

Объект, описывающий событие, содержит поля:

e

string Тип события. Всегда содержит значение ost_interaction.

post_id

string Строковый идентификатор записи (owner_id+_+post_id).

action

string Действие. Возможные значения:

  • •
    expand — раскрытие записи по кнопке «Показать больше»;
  • •
    open — открытие записи на отдельном экране;
  • •
    link_click — переход по ссылке из текста записи;
  • •
    attached_link_click — переход по ссылке, прикреплённой к записи;
  • •
    snippet_action — переход по ссылке в сниппете;
  • •
    audio_start — начал проигрывать музыку в записи;
  • •
    video_start — начал проигрывать видео в записи
  • •
    open_photo — открытие фотографии из записи;
  • •
    open_layer — открытие статьи из записи;
  • •
    open_wiki — открытие вики-страницы;
  • •
    open_group — переход в группу;
  • •
    open_user — переход к пользователю.

ad_data

string Значение ad_data из объекта рекламной записи.

track_code

(string) Значение поля track_code из объекта записи.

link

string URL ссылки. передаётся, если action — link_click, attached_link_click или snippet_action. Для хэштегов передается сам хэштег в виде #hashtag. Для ссылок передается значение в оригинальном виде: example.com, https://vk.com/samsung;, ... Для mention-ссылок передаётся ссылка, преобразованная в https://vk.com/....

Внимание! Метод stats.trackEvents нужно вызвать не позднее, чем в течение 1 минуты после того, как произошло событие.