Контекстная реклама
Редакция Yagla
API Яндекс.Директ: руководство по применению
Статья
59662
API Яндекс.Директа – это интерфейс рекламной системы для разработчиков программ. Он позволяет автоматизировать работу с Яндекс.Директ и использовать все его функции – от получения статистики до создания рекламных кампаний с нуля. И всё абсолютно бесплатно.
Результат работы с API – ваше приложение по управлению контекстной рекламой в Яндекс.Директ с собственными настройками и алгоритмами. Кстати, для этого совсем не обязательно быть профи в программировании – достаточно базовых знаний PHP или Python.
Как всё это применять и что нужно, чтобы начать работу – смотрите в этой статье.
Для чего нужен API Яндекс.Директ
API Директа дает возможность разрабатывать и внедрять алгоритмы для управления рекламными кампаниями под ваши нужды. Это пригодится как агентствам, так и крупным рекламодателям, которые запускают и ведут масштабные кампании. Их деятельность предполагает множество рутинных действий, например:
- Массовое создание и редактирование кампаний, объявлений и ключевых фраз;
- Управление ставками;
- Получение статистики по показам и кликам;
- Прогноз бюджета.
Инструмент API позволяет создать приложение, в котором все нужные вам однотипные операции выполняются автоматически и в котором можно создавать удобные инструменты для просмотра и редактирования кампаний. Автоматизировать можно практически всё, даже обновление цены за клик по заданному вами алгоритму.
Вы разрабатываете что-то наподобие Директ Коммандера. Эта программа – готовое решение Яндекса на основе API Яндекс.Директа. Как её применять, смотрите руководство по старой и новой версиям.
Приложения, созданные по API Яндекс.Директа, рассчитаны на пользователей, у которых есть аккаунт в Директе. Это прямые рекламодатели, агентства и их клиенты с доступом только на чтение (могут только получать и просматривать данные) или на редактирование (они получают в API все те же самые функции, что в интерфейсе).
Структура API
По сути API Директа – это набор сервисов, каждый из которых привязан к конкретному классу объектов и имеет отдельный URL. Объекты 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. Нажмите кнопку «Зарегистрировать новое приложение»:
В правой части страницы – ссылки на справочные материалы для разработчиков.
Далее вы попадаете на форму «Создание приложения», где нужно указать все его необходимые параметры:
Обязательные опции помечены звездочкой, это «Название» и «Доступы». Но чем больше информации о приложении вы укажете, тем более прозрачно оно будет для пользователей. Они будут знать, какой именно программе разрешают доступ к своему аккаунту.
В блоке «Платформы» отметьте галочкой «Веб-сервисы»:
Появится поле адреса. В нем вы указываете, куда направлять пользователя после того, как он разрешил или отказал приложению в доступе. Адресов Callback URI может быть несколько, например, для тестового и боевого режима.
На этапе создания приложения нажмите ссылку «Подставить URL для разработки».
В поле появится тестовый адрес, который позволит получать отладочные токены вручную. Они нужны для проверки работы приложения, подробнее об этом далее в статье.
В блоке «Доступы» выберите «Яндекс.Директ» и отметьте «Использование API Яндекс.Директа»:
Завершите создание приложения:
На этом регистрация закончена. При этом OAuth-сервер Яндекса сразу же генерирует и показывает на странице идентификатор и пароль приложения.
Они понадобятся вам далее.
Шаг 2: создание заявки на доступ
В аккаунте Яндекс.Директа долистайте до нижнего меню и перейдите по ссылке «API»:
Далее нажмите «Получить доступ к API»:
Вы попадете на страницу настроек API. Чтобы она была доступна, нужно выполнить формальное требование: в интерфейсе Яндекс.Директа должна быть минимум одна рекламная кампания с одним объявлением и одной ключевой фразой.
При первом входе нужно принять пользовательское соглашение:
На странице «Настройки API» перейдите на вкладку «Мои заявки», чтобы создать и отправить заявку на доступ к API. Нажмите кнопку «Новая заявка» и выберите её тип.
Тестовый доступ – это ограниченный доступ к API, то есть только к Песочнице – тестовой среде для отладки приложений. Она имитирует работающие рекламные кампании, их достаточно для того, чтобы протестировать и отладить приложение. Полный доступ (боевой) дает возможность управлять реальными рекламными кампаниями клиентов.
Так как приложение еще не разработано, создайте заявку на тестовый доступ. Для этого:
1) Из выпадающего списка выберите идентификатор, который получили после регистрации приложения на OAuth-сервере:
2) Укажите email для связи со службой поддержки;
3) Заполните остальные данные о приложении по максимуму – укажите, для чего оно предназначено, его основные функции и возможности и т.д.:
4) Подтвердите согласие с пользовательским соглашением и отправьте заявку.
Статус заявки отслеживайте здесь же – на вкладке «Мои заявки» в настройках. Дождитесь её одобрения – это может занять до 7 дней. Только после этого можно начинать разрабатывать приложение. В случае отклонения – узнайте причины и исправьте ошибки.
На стадии рассмотрения можно преобразовывать заявку на ограниченный доступ в заявку на полный доступ. После внесения любых изменений она автоматически отправляется на повторное рассмотрение.
На вкладке «Мои приложения» можно увидеть, какие приложения уже имеют доступ к аккаунту Яндекс.Директ через API. В том числе, если вы использовали Директ.Коммандер, он появится в этом списке:
Шаг 3: создание тестового пользователя и тестовых данных для него
1) Зарегистрируйте аккаунт тестового пользователя в Яндекс.Директе;
2) Создайте от его имени рекламную кампанию в интерфейсе Яндекс.Директа – достаточно одного объявления с одним ключевиком, чтобы получить доступ к API;
3) В разделе API интерфейса Директа нажмите ссылку «Получить доступ к API» и примите пользовательское соглашение;
4) Включите песочницу – среду для отладки приложения, где можно управлять тестовыми кампаниями без реальных показов и внесения средств.
Для этого откройте вкладку «Песочница» на странице настроек API и начните ею пользоваться:
В следующем окне задайте параметры песочницы:
Поставьте галочку «Создать тестовые кампании». Если вы выбрали роль «Клиент» создаются три кампании. Для роли «Агентство» – 3 клиента с 3 кампаниями, их логины формируются автоматически. На одну кампанию каждого клиента зачисляется некоторая сумма.
Включение флажка «Общий счет» создает клиента с подключенным общим счетом. Для агентства опция недоступна.
Нажмите «Продолжить», чтобы начать управлять песочницей.
Внимание! Если сменить параметры, все данные удаляются. Нужно создавать песочницу заново.
5) От имени тестового пользователя получите отладочный токен. С помощью него можно проверять работу приложений.
Когда пользователь авторизуется в Яндекс.Директе и нажимает кнопку «Подтвердить», то есть дает доступ к своим данным приложения, сервер Яндекса генерирует токен и передает его приложению.
Как всё происходит:
- Приложение направляет пользователя на страницу Яндекс.OAuth;
- На этой странице пользователь разрешает доступ к своим данным приложению;
- Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL. Код подтверждения или описание ошибки передается в параметре URL перенаправления;
- Приложение получает адрес перенаправления и извлекает код подтверждения;
- Приложение отправляет POST-запрос с этим кодом;
- Яндекс.OAuth возвращает токен в теле ответа.
Если объяснять с технической стороны, запрос к API выполняется по протоколу HTTPS методом POST (отправление данных). В этом запросе содержится HTTP-заголовок с токеном пользователя, от имени которого осуществляется запрос. Ответ содержит заголовок RequestId – это уникальный идентификатор запроса.
Некоторые приложения (например, консольные или установленные на телевизорах Smart TV) не могут получить код подтверждения из URL. В этом случае пользователь самостоятельно его получает от Яндекс.OAuth и вводит в приложении или на странице авторизации.
Полученный токен используется для запросов к 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 – при просмотре и редактировании кампаний, рекламных групп, объявлений и ключевых фраз не нужно ждать загрузки страниц, как в интерфейсе Яндекс.Директа. И конечно, это экономит время специалистов по настройке контекстной рекламы.
Метки: Контекстная реклама, Яндекс директ
59662
1 Читайте ещё статьи по этой теме
Как сделать кликабельный номер телефона на сайте Статья
Когда пользователь может в один клик по номеру телефона сделать звонок, это в плюс и ему, и вам. Он тратит минимум усилий и времени, чтобы вам дозвониться, а вы получаете +1 целевой звонок.1
Key Collector: полное практическое руководство Статья
Key Collector – инструмент парсинга, который на слуху у всех, кто когда-либо сталкивался со сбором семантики. Что может остановить и заставить делать выбор не в пользу этой программы?Во-первых, наличие бесплатного аналога – Словоеба.1
Как составить список минус-слов вручную и автоматически Статья
Ни для кого не секрет, что рекламироваться по нецелевым запросам = сливать рекламный бюджет. Выход – заносить их в список минус-слов.
Написать комментарий
Maxim MachovikovMarch 6, 2019 в 11:36 AM
Ничетак статейка
Обсуждаемое
Как мы увеличили посещаемость ТЦ с товарами для стройки и ремонта: SEO и РК в конкурентной нише Статья
Рассказываем, как использовали SEO и интернет-рекламу, чтобы увеличить посещаемость стройцентра на 3-5% в месяц. Ситуация усложнялась падающим спросом на рынке в категории ремонта и строительства.2
Подводные камни в продвижении через видео: 5 причин, почему опускаются руки Статья
Казалось бы, что сложного в том, чтобы сниматься в экспертных видеороликах? Можно просто говорить на камеру и выкладывать это хоть каждый день. Но когда доходит до дела, начинают проявляться разные скрытые моменты, которые иногда полностью блокируют создание контента.1
Как снизить стоимость лида при помощи маркет-платформы ВКонтакте: на примере одного проекта Статья
Продукт – защитная пленка на стол, который защищает поверхность от царапин. Замена старой дедовской скатерти.1
Свежее
Эффективное продвижение брендов с помощью контекстной рекламы Статья
Речь пойдет именно о стратегиях и подходах с точки зрения маркетинга к запуску каких-то необычных проектов. .
РСЯ от А до Я: как работать с рекламными сетями Статья
Для новичков: РСЯ – это рекламная сеть Яндекса с более чем 50 000 ресурсов: сайты, мобильные приложения, приложения Smart TV. Еще это сами сервисы Яндекса – почта, картинки, погода и многое другое.
Сегменты аудиторий в Яндекс.Директ: советы по использованию инструмента Статья
Аудитория, на которую мы настраиваем рекламу в Директе, неодородна. Даже если люди вбивают одинаковые ключевые слова, они отличаются друг от друга поведением в интернете, готовностью купить/заказать, геолокацией, интересами и потребностями, полом и возрастом и т.
