API Яндекс.Директ: руководство по применению

0
53

API Яндекс.Директ: руководство по применению

API Яндекс.Директа – это интерфейс рекламной системы для разработчиков программ. Он позволяет автоматизировать работу с Яндекс.Директ и использовать все его функции – от получения статистики до создания рекламных кампаний с нуля. И всё абсолютно бесплатно.

Результат работы с API – ваше приложение по управлению контекстной рекламой в Яндекс.Директ с собственными настройками и алгоритмами. Кстати, для этого совсем не обязательно быть профи в программировании – достаточно базовых знаний PHP или Python.

Как всё это применять и что нужно, чтобы начать работу – смотрите в этой статье.

Для чего нужен API Яндекс.Директ

API Директа дает возможность разрабатывать и внедрять алгоритмы для управления рекламными кампаниями под ваши нужды. Это пригодится как агентствам, так и крупным рекламодателям, которые запускают и ведут масштабные кампании. Их деятельность предполагает множество рутинных действий, например:

  • Массовое создание и редактирование кампаний, объявлений и ключевых фраз;
  • Управление ставками;
  • Получение статистики по показам и кликам;
  • Прогноз бюджета.

Инструмент API позволяет создать приложение, в котором все нужные вам однотипные операции выполняются автоматически и в котором можно создавать удобные инструменты для просмотра и редактирования кампаний. Автоматизировать можно практически всё, даже обновление цены за клик по заданному вами алгоритму.

Вы разрабатываете что-то наподобие Директ Коммандера. Эта программа – готовое решение Яндекса на основе API Яндекс.Директа. Как её применять, смотрите руководство по старой и новой версиям.

Приложения, созданные по API Яндекс.Директа, рассчитаны на пользователей, у которых есть аккаунт в Директе. Это прямые рекламодатели, агентства и их клиенты с доступом только на чтение (могут только получать и просматривать данные) или на редактирование (они получают в API все те же самые функции, что в интерфейсе).

Структура API

По сути API Директа – это набор сервисов, каждый из которых привязан к конкретному классу объектов и имеет отдельный URL. Объекты API взаимосвязаны между собой, как показано на скриншоте:

API Яндекс.Директ: руководство по применению

Изображение из руководства Яндекса для разработчиков

Сервисы верхнего уровня – Campaign и AdGroup. Первый содержит настройки рекламной кампании, второй нужен для работы с группами объявлений.

На следующем уровне – сервисы Ad (параметры объявления), Keyword (ключевые фразы), Audience Target (условия нацеливания на аудиторию) и DynamicTextAdTarget (условия нацеливания для динамических объявлений).

Далее идут сервисы для работы с элементами объявления: AdImage (изображениями), VCard (виртуальной визиткой), SitelinksSet (блоком быстрых ссылок), AdExtension (расширением к объявлению).

Для управления условиями ретаргетинга и подбора аудитории есть специальный сервис – RetargetingList.

У каждого сервиса свой набор методов для выполнения операций с его объектами. Основные методы, которые доступны для всех объектов – это добавление (add), изменение параметров (update), удаление (delete) и получение параметров (get).

Есть также специфические методы, которые поддерживают определенные объекты. Например, отправление объявлений на модерацию (moderate) – метод для сервиса Ads. Весь список доступных методов по областям применения смотрите в документации API.

Итак, с чего начать, чтобы разработать собственное приложение для работы с контекстной рекламой в Яндекс.Директе? Во-первых, нужен доступ к API. Далее рассмотрим пошагово, как его получить.

Шаг 1: создание и регистрация приложения на Яндекс.OAuth

Авторизуйтесь в Яндекс.Директе. Используйте для этого аккаунт разработчика – именно от этого имени ваше приложение будет выполнять запросы и управлять данными.

Перейдите по ссылке oauth.yandex.ru. Нажмите кнопку «Зарегистрировать новое приложение»:

API Яндекс.Директ: руководство по применению

В правой части страницы – ссылки на справочные материалы для разработчиков.

Далее вы попадаете на форму «Создание приложения», где нужно указать все его необходимые параметры:

API Яндекс.Директ: руководство по применению

Обязательные опции помечены звездочкой, это «Название» и «Доступы». Но чем больше информации о приложении вы укажете, тем более прозрачно оно будет для пользователей. Они будут знать, какой именно программе разрешают доступ к своему аккаунту.

В блоке «Платформы» отметьте галочкой «Веб-сервисы»:

API Яндекс.Директ: руководство по применению

Появится поле адреса. В нем вы указываете, куда направлять пользователя после того, как он разрешил или отказал приложению в доступе. Адресов Callback URI может быть несколько, например, для тестового и боевого режима.

На этапе создания приложения нажмите ссылку «Подставить URL для разработки».

API Яндекс.Директ: руководство по применению

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

В блоке «Доступы» выберите «Яндекс.Директ» и отметьте «Использование API Яндекс.Директа»:

API Яндекс.Директ: руководство по применению

Завершите создание приложения:

API Яндекс.Директ: руководство по применению

На этом регистрация закончена. При этом OAuth-сервер Яндекса сразу же генерирует и показывает на странице идентификатор и пароль приложения.

API Яндекс.Директ: руководство по применению

Они понадобятся вам далее.

Шаг 2: создание заявки на доступ

В аккаунте Яндекс.Директа долистайте до нижнего меню и перейдите по ссылке «API»:

API Яндекс.Директ: руководство по применению

Далее нажмите «Получить доступ к API»:

API Яндекс.Директ: руководство по применению

Вы попадете на страницу настроек API. Чтобы она была доступна, нужно выполнить формальное требование: в интерфейсе Яндекс.Директа должна быть минимум одна рекламная кампания с одним объявлением и одной ключевой фразой.

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

API Яндекс.Директ: руководство по применению

На странице «Настройки API» перейдите на вкладку «Мои заявки», чтобы создать и отправить заявку на доступ к API. Нажмите кнопку «Новая заявка» и выберите её тип.

API Яндекс.Директ: руководство по применению

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

Так как приложение еще не разработано, создайте заявку на тестовый доступ. Для этого:

1) Из выпадающего списка выберите идентификатор, который получили после регистрации приложения на OAuth-сервере:

API Яндекс.Директ: руководство по применению

2) Укажите email для связи со службой поддержки;

3) Заполните остальные данные о приложении по максимуму – укажите, для чего оно предназначено, его основные функции и возможности и т.д.:

API Яндекс.Директ: руководство по применению

4) Подтвердите согласие с пользовательским соглашением и отправьте заявку.

API Яндекс.Директ: руководство по применению

Статус заявки отслеживайте здесь же – на вкладке «Мои заявки» в настройках. Дождитесь её одобрения – это может занять до 7 дней. Только после этого можно начинать разрабатывать приложение. В случае отклонения – узнайте причины и исправьте ошибки.

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

На вкладке «Мои приложения» можно увидеть, какие приложения уже имеют доступ к аккаунту Яндекс.Директ через API. В том числе, если вы использовали Директ.Коммандер, он появится в этом списке:

API Яндекс.Директ: руководство по применению

Шаг 3: создание тестового пользователя и тестовых данных для него

1) Зарегистрируйте аккаунт тестового пользователя в Яндекс.Директе;

2) Создайте от его имени рекламную кампанию в интерфейсе Яндекс.Директа – достаточно одного объявления с одним ключевиком, чтобы получить доступ к API;

3) В разделе API интерфейса Директа нажмите ссылку «Получить доступ к API» и примите пользовательское соглашение;

4) Включите песочницу – среду для отладки приложения, где можно управлять тестовыми кампаниями без реальных показов и внесения средств.

Для этого откройте вкладку «Песочница» на странице настроек API и начните ею пользоваться:

API Яндекс.Директ: руководство по применению

В следующем окне задайте параметры песочницы:

API Яндекс.Директ: руководство по применению

Поставьте галочку «Создать тестовые кампании». Если вы выбрали роль «Клиент» создаются три кампании. Для роли «Агентство» – 3 клиента с 3 кампаниями, их логины формируются автоматически. На одну кампанию каждого клиента зачисляется некоторая сумма.

Включение флажка «Общий счет» создает клиента с подключенным общим счетом. Для агентства опция недоступна.

Нажмите «Продолжить», чтобы начать управлять песочницей.

Внимание! Если сменить параметры, все данные удаляются. Нужно создавать песочницу заново.

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

Когда пользователь авторизуется в Яндекс.Директе и нажимает кнопку «Подтвердить», то есть дает доступ к своим данным приложения, сервер Яндекса генерирует токен и передает его приложению.

Как всё происходит:

  • Приложение направляет пользователя на страницу Яндекс.OAuth;
  • На этой странице пользователь разрешает доступ к своим данным приложению;
  • Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL. Код подтверждения или описание ошибки передается в параметре URL перенаправления;
  • Приложение получает адрес перенаправления и извлекает код подтверждения;
  • Приложение отправляет POST-запрос с этим кодом;
  • Яндекс.OAuth возвращает токен в теле ответа.

Если объяснять с технической стороны, запрос к API выполняется по протоколу HTTPS методом POST (отправление данных). В этом запросе содержится HTTP-заголовок с токеном пользователя, от имени которого осуществляется запрос. Ответ содержит заголовок RequestId – это уникальный идентификатор запроса.

Некоторые приложения (например, консольные или установленные на телевизорах Smart TV) не могут получить код подтверждения из URL. В этом случае пользователь самостоятельно его получает от Яндекс.OAuth и вводит в приложении или на странице авторизации.

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

Далее вы выполняйте запросы к песочнице. Вот пример запроса:

API Яндекс.Директ: руководство по применению

Практика использования API Яндекс.Директ

В инструменте API множество методов для разных объектов, многие из них дорабатываются и улучшаются со временем. Рассмотрим подробно, как их применять на практике.

Для примера возьмем создание отчета по поисковым запросам, прогноз бюджета и ретаргетинг. Этому действию соответствует метод CreateNewWordstatReport. Он запускает на сервере формирование отчета о статистике поисковых запросов. Это занимает не больше минуты.

Отчет содержит ту же статистику, которая доступна в сервисе Яндекс Wordstat за прошедший месяц.

Ограничения:

  • За сутки можно получить статистику для тысячи фраз;
  • На сервере хранится максимум 5 отчетов по всем кампаниям;
  • Отчеты хранятся на сервере в течение 5 часов, а затем автоматически удаляются.

Так выглядит структура входных данных в формате JSON:

{

   "method": "CreateNewWordstatReport",

   "param": {

      /* NewWordstatReportInfo */

      "Phrases": [

         (string)

         …

      ],

      "GeoID": [

         (int)

         …

      ]

   }

}

Phrases – это массив ключевых фраз, по которым нужно получить статистику поисковых запросов (добавить можно не более 10). минус-фразы из нескольких слов пишите в скобках, например: холодильник -морозильник -(морозильная камера) -ремонт.

GeoID – идентификаторы регионов, по которым нужно получить статистику поисковых запросов. Можно исключить регион, поставив минус. Если вы не указали этот параметр, либо указали только минус-регионы, либо минус-регионы совпадают c плюс-регионами, статистика выдается по всем регионам.

Вообще в API Яндекс.Директа можно решать самые разнообразные задачи, например:

— Интегрировать функции Яндекс.Директ и данные из собственной базы.

Примеры применения: автоматическое добавление в ключевые фразы названий брендов или моделей товаров, остановка / возобновление показов объявлений в зависимости от наличия товаров на складе, обновление текстов объявлений при изменении прайс-листа. И многое другое, в зависимости от данных, которые у вас есть;

— A/B-тестирование объявлений.

Принцип тот же, что в интерфейсе: в самом начале все варианты из группы объявлений показываются равномерно. По мере накопления статистики система выбирает объявление с самым высоким CTR (самое привлекательное по мнению целевой аудитории) и показывает его чаще;

— Мониторинг и анализ эффективности рекламных кампаний.

Можно настроить автоматическое получение сводной и детальной статистики по показам, кликам, конверсиям и другим показателям и выгрузку её в сторонние программы (системы поддержки принятия решений, системы финансового учета и т.д.)

Все примеры использования API смотрите в меню «Практика использования» по ссылке.

Важное преимущество программы на основе API – при просмотре и редактировании кампаний, рекламных групп, объявлений и ключевых фраз не нужно ждать загрузки страниц, как в интерфейсе Яндекс.Директа. И конечно, это экономит время специалистов по настройке контекстной рекламы.

ОСТАВЬТЕ ОТВЕТ

Please enter your comment!
Please enter your name here