PHP и Яндекс Директ: наш опыт использования
18 июня Яндекс анонсировал публичный доступ к API Яндекс Директ. Мы, как рекламное агентство, получили этот доступ немного раньше и сейчас используем его для управления ставками в рекламных кампаниях. Хотелось бы поделиться нашим опытом.
Первоначальные наши впечатления от API были достаточно противоречивые, все таки заметно, что это первая версия. Местами присутствуют несуразности в именовании элементов API, зачастую избыточна, на наш взгляд, система типов параметров методов.
Нашей целью было предоставить разработчикам проектов относительно простой механизм описания правил автоматического формирования ставок, при этом разработчик должен легко описывать тривиальные ситуации и иметь возможность реализовать произвольный алгоритм, если это потребуется отделам рекламы или продвижения интернет-проектов.
Использование чистого API в этой связи мы сочли малоперспективным 🙂 и решили написать над ним более удобный враппер.
Мы сразу же столкнулись с одним неприятным моментом. API использует протокол SOAP, на сервере используется SOAP::Lite. SOAP::Lite имеет некие специфические особенности при формировании представления массивов объектов, возвращаемых SOAP-методами, в результате которых на клиенте при использовании стандартного PHP-модуля SOAP Client cтановится невозможным использовать опцию classmap.
Эта опция позволяет связать типы данных SOAP с классами объектов, представляющими эти типы, и без нее, вообще-то, плохо. С другими реализациями SOAP-сервера, например на Java, такой проблемы не возникает, проверено на сервисах Google и разных других. Честно говоря, наших знаний о SOAP недостаточно, чтобы предложить вменяемый выход из этой ситуации, проблема скорее всего на стороне PHP, а не SOAP::Lite. Яндекс в свою очередь рекомендует использовать NuSOAP.
В общем, протокол вроде бы и стандартный, а щастья нет 🙁
Кстати говоря, для нормальной работы, скажем, с Google Adwords API, запрос, формируемый стандартным PHP Soap Client, приходится нещадно патчить, примеры можно посмотреть в исходниках PHP-клиента для этого сервиса.
Использовать NuSOAP мы убоялись и решили обойтись без classmap, работаем с простыми stdClass-объектами, которые возвращает API, добавляя по необходимости к ним поведение при помощи объектов-врапперов. Кроме того, врапперы выполняют трансляцию имен свойств из нашего стандарта (с подчеркиваниями) в CamelCase — хорошо, когда все единообразно.
Таким образом, разработчик может вызывать методы API в стандартной нотации нашей библиотеки, с логированием вызовов, выдерживанием временных промежутков между ними и т.д.
Основываясь на этом, добавляем поведение в сущности и коллекции. Использование собственных коллекций нам очень пригодилось, поскольку позволяет, например, писать так:
В настоящее время для большинства выборок в API отсутствует возможность применять правила фильтрации (некоторые методы позволяют, но не все). Поскольку выборка по различным условиями нам нужна, пришлось реализовывать ее на клиенте опять же в базовом классе коллекции.
В данном случае из набора фраз, который был возвращен веб-сервисом, мы отбираем фразы, начинающиеся на «рекламная фотосъемка» и «фотосъемка рекламы».
Where-условие представляет собой массив, ключи которого содержат имя поля, на которое накладывается условие, и операцию, которая используется для сопоставления, а значения — образец или список образцов, с которыми производится сопоставление. Результат выполнения — коллекция того же класса, что и исходная, но содержащая отфильтрованные элементы.
Пока нам хватает таких операций:
Теперь о том, как мы приспособили все это для разработчиков проектов.
Для каждого проекта создается сценарий управления рекламной кампанией. Он представляет собой PHP-скрипт, например следующего вида:
Сценарии запускаются приложением командной строки, реализованным в виде модуля Service.Yandex.Direct.Manager, приложение, в свою очередь, запускается кроном.
В каждом вызове мы определяем список объявление, для которых нужно изменить цены. Это делается путем последовательной выборки «кампании → объявления → фразы».
На самом деле, нас интересуют цены, а цены привязаны к фразам. Однако приложение умеет само достраивать недостающие звенья цепочки. Полное выражение в нашем случае выглядело бы так:
В принципе, ничего не мешает писать в файле сценария код, выполняющий те или иные действия над ценами и вызывающий затем стандартный метод update_prices(). Например, можно было бы написать так:
Приведенный выше код проходит по всем фразам, проверяет, обеспечивает ли текущая ставка показ в спецразмещениях, и соответствующим образом корректирует ее.
Если проект предъявляет какие-то особые требования к управлению кампанией, так и нужно делать, однако в большинстве проектов задачи по управлению ценами как правило сходные и очень простые, поэтому можно выделить эти стандартные действия в готовые методы, реализующие ту или иную стратегию изменения ставок.
Программист тестирует сценарий, после чего сценарий добавляется в приложение, управляющее кампаниями. Пока нам хватает одного процесса, но вообще можно запускать несколько экземпляров менеджера кампаний с отдельными очередями для разных клиентов.
Что мы получили в итоге? Написание объектного враппера над SOAP API позволило нам минимизировать количество кода для решения рутинных задач и в то же время сделать этот код достаточно читаемым для того, чтобы при необходимости даже непрограммист мог понять, по каким правилам формируются ставки. При этом мы оставляем для программиста возможность реализации произвольного алгоритма манипулирования ставками.
Автоматизация Яндекс.Директ. Часть 1
Совместно с коллегами из ADF Media — Артемом Дурневым и Султаном Назаралиевым, мы решили выпустить цикл из 6 статей, посвященных автоматизации процессов в Яндекс Директе. Сегодня вас ждет вступительная часть, в которой мы поговорим про API, токены Директа и Песочницу.
Чтобы автоматизировать работу Я.Директа, мы должны понимать, что такое API.
API — это составляющая часть сервиса, которая позволяет отправлять запросы и получать ответы.
Единого сценария работы с API нет. У каждого сервиса — сценарий свой. Единственное общее — это токены. Не важно с какой рекламной площадкой вы работаете, в любом случае вам нужно будет получать токен.
Токен — это «ключ» к сервису. Где-то токены нужно получать каждый час, а где-то вы должны владеть двумя «токенами» и передавать их на сервер, чтобы получать «истинный» токен в зашифрованном виде. А где-то вы просто получаете от системы один токен и пользуетесь им продолжительное время.
Так как мы говорим про Яндекс, то в нем получение токена организовано по принципу OAuth. Срок действия токена — один год.
OAuth — это протокол авторизации. Например, получив токен, вы можете передать его любому человеку для авторизации в сервисе, которым пользуетесь. Ему не нужно будет знать ваш логин и пароль, если у него есть токен.
Та же история с Я.Директом. Если вы передадите токен, человек сможет управлять рекламными кампаниями и скачивать данные из статистики за вас.
Токен Яндекс.Директа выглядит следующим образом:
Казалось бы, что это просто набор цифр и букв, но на самом деле каждый такой токен содержит следующую информацию:
Таким образом, токен показывает, что может делать данное приложение от имени определенного аккаунта.
Есть два варианта получения токена. Простой и сложный. Сложный заключается в том, что нам необходимо стать разработчиком и зарегистрировать приложение. Делается это следующим образом:
Указываем название приложения. В описании можно указать для чего создается приложение.
В графе «платформы” указываем веб-сервисы и нажимаем “Подставить URL для разработки».
Далее необходимо указать какие доступы мы можем запрашивать токеном.
После пройденных шагов, вы получите ID и пароль приложения.
После регистрации OAuth приложения нужно подать заявку на доступ к API Яндекс.Директ. Для этого заходим в Яндекс.Директ и переходим во вкладку API, как показано ниже.
Далее открываем «Мои заявки»
Смело нажимаем на «Полный доступ» и заполняем поля. Вот как заполнили мы:
В демо-доступе указали ссылку на Google Таблицу.
Срок рассмотрения заявки до 7 дней, но, как правило, рассмотрение занимает один-два дня. После этого заявка будет одобрена или отклонена. Как только приложение будет одобрено, вы сможете «вытаскивать» токены.
Переходим по ссылке вида:
(Не забудьте, поменять хвостик, заменив его на свой ID, который получили выше)
И в ответ на наш запрос — получаем токен.
Простой способ получения токена — Переходим на сайт ADF-media и авторизовываемся. В ответ на авторизацию, сайт покажет вам ваш токен.
Давайте сделаем первую часть цикла статей максимально полезной и поговорим еще и про Песочницу. Пока поверхностно, чтобы иметь о ней минимально представление.
Песочница — это среда для отладки приложений, взаимодействующих с API Директа.
Песочница имитирует API Директа, но полностью изолирована от настоящих данных. Это «игровая площадка», на которой можно вызывать методы API, получать ответы, наблюдать изменение тестовых кампаний и объявлений. Действия, которые доступны в API только при положительном балансе, в Песочнице доступны без фактического внесения средств.
Запросы к Песочнице не изменяют данные в Директе. Созданные объявления нигде не показываются, а списываемые и зачисляемые средства не влияют на настоящие кампании. Однако для кампаний имитируется полный набор состояний — от модерации до остановки показов при исчерпании средств. Статистические отчеты хотя и содержат условные данные, но по структуре совпадают с настоящими отчетами. Это делает Песочницу полнофункциональной средой для отладки приложений.
Песочница не имеет веб-интерфейса, и посмотреть тестовые кампании в интерфейсе невозможно. Работать с Песочницей можно только через вызовы методов API.
Но нужно помнить, что:
Мы знаем, что такое API, как зарегистрировать приложение и зачем это нужно, а также понимаем, что такое Песочница.
в следующей статье, мы воспользуемся полученными знаниями для передачи первых данных из Яндекс.Директа в Google Таблицы (без знания программирования).
Api direct yandex php
Здесь мы будем рассказывать о новостях и тонкостях использования нашего API.
Подробное описание API представлено в документации. Также вам может пригодиться раздел с ответами на популярные вопросы.
Чтобы начать работу с API Яндекс.Директа, ознакомьтесь с информацией о доступе. Посмотрите рекомендации и требования к приложениям, если вы хотите написать на основе API свою программу.
Вопросы об API можно задавать через форму обратной связи.
Команда API Яндекс.Директа
В API Директа появился сервис DynamicFeedAdTargets. Он предназначен для выполнения операций с условиями нацеливания по фидам для динамических текстовых объявлений.
Примерно через восемь рабочих недель параметр StrategyPriority перестанет поддерживаться в сервисах:
Пожалуйста, запланируйте обновление своих приложений до конца января 2021 года. Мы напомним вам об изменениях перед тем, как они вступят в силу.
Если у вас появились вопросы, вы можете задать их специалистам службы поддержки.
В сервисе Campaigns, в стратегиях WB_MAXIMUM_CONVERSION_RATE,AVERAGE_ROI и AVERAGE_CPA ограничена возможность оптимизации по всем целям. Теперь в параметре GoalId для этих стратегий необходимо передавать идентификатор конкретной цели Яндекс.Метрики.
В сервисе Campaigns появились новые стратегии:
Стратегии принесут конверсии по цене, указанной при настройке стратегии.
Появилась поддержка профилей организаций из Яндекс.Справочника:
Смарт-баннеры — красивый и удобный формат Директа для ретаргетинга и генерации продаж, объявления с оплатой за клик и динамическим контентом. Чтобы вам было удобнее автоматизировать работу со смарт-баннерами, мы добавили возможность управлять ими в API Директа.
Какие нововведения появились в API:
Прочитать подробности об управлении смарт-баннерами через API можно в документации.
Добавлен таргетинг по интересам для текстово-графических объявлений:
Изменения подробно описаны в документации.
Метод Dictionaries.get возвращает в справочнике Currencies новый параметр MinimumAccountDailyBudget — минимальный дневной бюджет общего счета.
Валютный параметр MinimumPayment, который ранее совмещал два значения — минимальный платеж (без учета НДС) и минимальный дневной бюджет общего счета, используйте только в качестве ограничения минимального платежа.
Значения возвращаемых параметров SharedAccountFunds.Spend и CampaignFunds.Sum теперь включают НДС.
В сервисе Campaigns для настройки ADD_METRICA_TAG в структуре Settings значение по умолчанию изменено с NO на YES.
Таким образом, для новых кампаний настройка по умолчанию включена. Это означает, что к ссылкам объявлений автоматически добавляется метка ?yclid= с уникальным номером клика. Необходимо убедиться, что страницы сайта рекламодателя корректно открываются по ссылкам с этой меткой.
В методы сервиса Campaigns добавлен параметр AttributionModel для кампаний с типом «Текстово-графические объявления» и «Динамические объявления».
В сервисе Reports для входного параметра AttributionModels добавлено значение LYDC — «Последний переход из Яндекс.Директа». Статистика по новой модели атрибуции доступна за период начиная с 30 июля 2019 г.
Сервис Sitelinks теперь поддерживает до 8 быстрых ссылок в каждом наборе.
Суммарная длина текстов быстрых ссылок № 1–4 — не более 66 символов. Суммарная длина текстов быстрых ссылок № 5–8 — также не более 66 символов.
В сервис Campaigns внесены изменения, о которых мы сообщали ранее:
Изменения подробно описаны в документации.
Хотим предупредить вас, что в середине августа в сервисе Campaigns произойдут изменения, связанные с недавно анонсированным обновлением стратегий. Изменения затронут кампании с типом TEXT_CAMPAIGN и MOBILE_APP_CAMPAIGN.
Если на поиске автоматическая стратегия:
Если у вас появились вопросы, вы можете задать их специалистам службы поддержки.
В API Директа появилась поддержка наборов минус-фраз:
Если у вас появились вопросы, вы можете задать их специалистам службы поддержки.
Появилась поддержка видеообъявлений в медийных кампаниях:
Ограничение. Настройка Сбор аудитории видео в настоящее время не поддерживается в API.
Подробнее об управлении медийными кампаниями читайте в документации.
Хотим предупредить вас, что скоро к объявлениям в Директе можно будет добавить до восьми быстрых ссылок. Новый лимит начнет применяться в июне.
Изменения затронут сервис Sitelinks — если вы используете его, подготовьте свои приложения.
Любые вопросы вы можете задать специалистам службы поддержки API Директа.
Изменения, о которых мы писали ранее, вступили в силу: в API Директа появилась поддержка Турбо-страниц.
Параметр Href в структурах TextImageAd, TextAdBuilderAd, CpcVideoAdBuilderAd, CpmBannerAdBuilderAd стал nillable в методах Ads.update и Ads.get.
Параметры Href и Description стали nillable в методе Sitelinks.get.
В метод Sitelinks.get добавлен входной параметр SitelinkFieldNames.
Подробнее о Турбо-страницах читайте в документации.
Недавно мы запустили Турбо-страницы для десктопов. Теперь во многих типах объявлений ссылка на сайт стала необязательной — рекламодатель может указать только Турбо-страницу.
Что изменится в API
В сервисе Ads появится новое поле — TurboPageId. В структуре TextAd достаточно будет указать одно из полей Href, VCardId и TurboPageId.
В структурах TextImageAd, TextAdBuilderAd, CpcVideoAdBuilderAd, CpmBannerAdBuilderAd достаточно будет указать одно из полей Href и TurboPageId. Таким образом, поле Href станет необязательным в методе add, а в методах update и get оно станет nillable. Обратите внимание: метод get может вернуть nil (null) в поле Href — например, если рекламодатель удалил основную ссылку объявления. Приложение должно корректно обработать такой ответ.
В сервисе Sitelinks также появится поле TurboPageId. В структуре Sitelink достаточно будет указать одно из полей Href и TurboPageId. Кроме того, в методе get появится входной параметр SitelinkFieldNames: в нём можно перечислить имена полей быстрой ссылки, которые требуется получить. В ответе метода get поля Href и Description станут nillable — приложение также должно корректно обработать значение nil (null) в этих полях.
Список опубликованных Турбо-страниц рекламодателя можно будет получить с помощью нового метода — TurboPages.get.
Когда произойдут изменения
Поддержка Турбо-страниц в API появится ориентировочно через две-три недели. Пожалуйста, запланируйте обновление своих приложений. Если у вас появились вопросы, вы можете задать их специалистам службы поддержки API Директа.