Требования к приложению

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

Общие требования. Обработка ошибок

  1. Приложение должно протоколировать все запросы к API Директа и хранить логи запросов и ответов API не менее чем за последние 3 суток.
  2. Приложение должно контролировать и обрабатывать ошибки взаимодействия с API. Приложение не должно повторно отправлять некорректно сформированный запрос.
  3. Приложение должно контролировать количество одновременных запросов к API от имени одного пользователя (п. 1 раздела Технические ограничения).
  4. Приложение должно контролировать суммарное количество вызовов каждого метода от имени одного пользователя в течение суток (п. 2 раздела Технические ограничения).
  5. При возникновении ошибки, связанной с ограничениями на количество запросов, приложение должно прекращать выполнение запросов.
  6. Перед вызовом методов, для которых предусмотрены балльные ограничения (см. раздел Балльные ограничения), приложение должно контролировать наличие доступных баллов с помощью метода GetClientsUnits.

Назначение ставок

  1. Для назначения ставок следует использовать преимущественно метод SetAutoPrice. Для назначения единых ставок для массива фраз или баннеров, а также для назначения ставок, равных цене показа на определенной позиции с некоторой надбавкой, всегда следует использовать метод SetAutoPrice.
  2. Количество вызовов метода SetAutoPrice следует минимизировать. Оптимальное количество вызовов — не более 1 раза в час и не более 10 раз в сутки для каждой кампании.
  3. Если в приложении реализована собственная логика изменения ставок, которую невозможно реализовать с помощью метода SetAutoPrice, допускается назначение ставок методом UpdatePrices.
  4. Количество вызовов метода UpdatePrices следует минимизировать. Для этого следует включать в каждый вызов метода максимальное количество фраз, в том числе относящихся к разным объявлениям или группам объявлений одной кампании (с учетом ограничения, указанного в п. 3 раздела Технические ограничения).
  5. При вызове метода UpdatePrices следует использовать идентификаторы фраз (PhraseID), заранее сохраненные в кэше, вместо получения идентификаторов фраз перед каждым назначением ставок.
  6. Рекомендуется варьировать частоту назначения ставок в зависимости от приоритета кампаний или объявлений (групп объявлений). См. подраздел Механизм приоритизации.
  7. Не следует продолжать изменение ставок для остановленных кампаний и кампаний, на которых закончились средства.

Обновление кэша

  1. Полученные с сервера параметры кампаний, объявлений (групп объявлений), ключевых фраз следует сохранять в кэше (в локальной базе данных, в памяти, в файлах на диске и т. д.).
  2. Перед обновлением данных в кэше следует использовать метод GetChanges для проверки наличия изменений. Заново получать с сервера API Директа следует только те кампании и объявления (группы объявлений), в которых произошли изменения с момента предыдущего обновления кэша.
  3. Для получения списка кампаний следует использовать метод GetCampaignsList, для получения параметров кампаний — метод GetCampaignsParams. Оптимальное количество вызовов — не чаще 1 раза в час.
  4. Для получения параметров объявлений следует использовать метод GetBanners с параметром GetPhrases = "Yes" (получение сокращенного состава параметров, без результатов аукциона). В случае большого количества фраз следует вызывать метод GetBanners с параметром GetPhrases = "No", а затем получать фразы методом GetBannerPhrasesFilter (см. п. 5).

    В случае большого количества объявлений в кампании (~1000 и более) при получении объявлений следует использовать параметры Limit/Offset.

  5. Для получения ключевых фраз следует использовать метод GetBannerPhrasesFilter, указывая в параметре FieldsNames состав параметров, которые необходимо получить (например, FieldsNames = ["PhraseID","BannerID","Phrase","Price","ContextPrice","AutoBudgetPriority"], а в параметре BannerIDS — идентификаторы объявлений (оптимальное количество — от 100 до 300).
  6. Для высокоприоритетных кампаний или объявлений (групп объявлений) допускается более частое обновление кэша (см. подраздел Механизм приоритизации).

Механизм приоритизации

  1. Кампании, группы, объявления и/или фразы рекомендуется разделить на высоко- и низкоприоритетные. Например, можно присвоить высокий приоритет наиболее активным и важным кампаниям: с большим количеством кликов или высокой ценой клика.

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

  2. Для высокоприоритетных объектов допускается более частое назначение ставок и обновление кэша (при условии выполнения п. 3).
  3. Для низкоприоритетных объектов следует уменьшить периодичность назначения ставок и обновления кэша: до 1–2 раза в сутки.

Контроль статистики расходов

  1. Для получения сводной статистики кампании по дням или за период необходимо использовать метод GetSummaryStat. Оптимальная периодичность вызова — не чаще 5 раз в час для каждой кампании.
  2. Для получения статистики по объявлениям и фразам необходимо использовать метод GetBannersStat (Live). Оптимальная периодичность вызова — не чаще 1 раза в час для каждой кампании.
  3. Метод CreateNewReport следует применять только для получения статистики в разрезе регионов показа, площадок, позиций показа, достижения целей Яндекс Метрики. При этом отчетный период следует ограничивать минимальным возможным значением (например, 1–2 дня). Оптимальная периодичность вызова — не чаще 5 раз в сутки для каждой кампании.
  4. При необходимости получить несколько отчетов методом CreateNewReport следует запустить формирование сразу максимального количества отчетов (с учетом ограничения, указанного в п. 6 раздела Технические ограничения). Это ускоряет обработку очереди запросов. По мере готовности отчетов следует скачивать их, удалять с сервера (метод DeleteReport) и запускать формирование следующего отчета.
  5. Проверку готовности отчетов (метод GetReportList) следует выполнять в одном потоке, не чаще 1 раза в 10–30 секунд. Рекомендуется увеличивать интервал перед каждой следующей проверкой, например: 10, 20, 40, ... секунд.
  6. Если требуется повышенная точность статистики с учетом корректировок, необходимо использовать метод GetChanges для проверки наличия корректировок статистики. Заново получать статистику следует только по тем кампаниям и периодам, по которым статистика была скорректирована.

Прогноз бюджета и подбор фраз

  1. Отчеты, формируемые методами CreateNewForecast и CreateNewWordstatReport, предназначены для расширения и уточнения рекламных кампаний клиентов в Директе. Не следует формировать данные отчеты для других целей.
  2. При необходимости получить несколько отчетов следует запустить формирование сразу максимального количества отчетов (с учетом ограничения, указанного в п. 6 раздела Технические ограничения). Это ускоряет обработку очереди запросов. По мере готовности отчетов следует получать их (методы GetForecast, GetWordstatReport), удалять с сервера (методы DeleteForecastReport, DeleteWordstatReport) и запускать формирование следующих отчетов.
  3. Проверку готовности отчетов (методы GetForecastList, GetWordstatReportList) следует выполнять в одном потоке, не чаще 1 раза в 10–30 секунд.
  4. Перед вызовом методов CreateNewWordstatReport и GetKeywordsSuggestion приложение должно контролировать наличие доступных баллов с помощью метода GetClientsUnits (см. раздел Балльные ограничения).

Словарные данные

  1. Список регионов (метод GetRegions) и временных зон (метод GetTimeZones) следует получить с сервера однократно и сохранить в кэше.
  2. Перед обновлением данных в кэше следует использовать метод GetChanges для проверки наличия изменений. Периодичность проверки — не чаще 1 раза в сутки.