YiiDirectApi

YiiDirectApi обеспечивает работу с API Yandex.Direct для фреймворка Yii.

Использование

Перед использованием данного расширения необходимо зарегистрировать приложение, которое будет работать с API Яндекс.Директа. После регистрации приложению будут присвоены id приложения и пароль приложения.

Установка и настройка расширения

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

В конфиге приложения добавьте компонент:

'direct' => array(
    'class' => 'ext.YiiDirectApi.YiiDirectApi',
    'id' => 'ид приложения',
    'password' => 'пароль приложения',
    'useSandbox' => true, # использовать ли песочницу. по умолчанию false — использует боевое API
    'locale' => 'ru', # на каком языке отдавать ответы. Если не указан, то используется язык приложения
    'responseType' => 'code', # Тип ответа от яндекса при получении токена (code, token). Если не указан, то используется code. 
),

Получение токена

Для получения токена необходимо отправить пользователя на страницу Яндекс.Директа. Ссылку на эту страницу можно получить следующим образом:

$link = Yii::app()->direct->getAuthorizeUrl();

В метод getAuthorizeUrl() можно передать также параметр $state, который будет возвращен в неизменном виде от Яндекса.

После того, как пользователь перейдет по сгенерированной ссылке и разрешит доступ, яндекс вернет на url, который был указан при регистрации приложения, код (и если был указан параметр state, то его в неизменном виде).

Для того, чтобы получить токен, нужно передать параметр code, который вернет Яндекс, методу getDirectToken($code)

$token = Yii::app()->direct->getDirectToken($code);

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

При получении токена через этот метод расширение его запомнит. Если приложение будет пользоваться доступом к данным Яндекс.Директа определенного аккаунта, тогда токен лучше сохранить в какое-нибудь постоянное хранилище.

Для дальнейшей работы приложения необходимо знать логин пользователя в Яндекс.Директ.

Запросы к API

Запросы к API осуществляются через методы расширения, названия которых соответствуют названиям методов API Яндекс.Директа, но начинаются с маленькой буквы. Например, в API Яндекс.Директа есть метод GetBanners; сделать запрос к нему можно через метод расширения getBanners(). Каждый метод может принимать массив $param, который содержит в себе необходимые данные для выполнения метода. Для некоторых методов этот массив указывать не обязательно. Содержимое $param описано для каждого метода API Яндекс.Директа. Рассмотрим запрос к API на примере метода GetBanners:

$res = Yii::app()->direct->getBanners(array(
    'CampaignIDS' => array(100, 101, 123),
    'GetPhrases' => 'WithPrices'
));

Каждый метод возвращает ответ от Яндекса (обычно это массив) в случае успеха, или false в том случае, если произошла ошибка.

Обработка ошибок

Для того, чтобы получить информацию об ошибке, можно воспользоваться методами:

getError() - вернет код ошибки
getErrorStr() - вернет строку ошибки
getErrorDetail() - вернет детальную информацию об ошибке (не всегда есть)

Установка логина и токена, при получении данных из локального хранилища

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

Yii::app()->direct->setLogin('login')->setToken('token');

Поддерживаемые методы

Сейчас расширение не дает доступ ко всем методам API Яднекс.Директа. Но реализовано большинство. Не реализованы методы из группы "Метки объявлений", "Изображения в объявлениях", "Ретаргетинг" и "Финансовые операции".

Буду очень рад дополнениям. Спасибо.

iamsalnikov / YiiDirectApi

readme