# KClient PHP

advanced expert team enterprise

KClient PHP — это один из методов отслеживания трафика и целевых действий на сторонних сайтах. Подключает Keitaro к удаленным ресурсам посредством PHP—кода. При клике по ссылке сайта выполняет действия и настройки кампании, которую подключаете к сайту. Выполняет динамическую подмену контента без видимого редиректа.

Метод подходит для любых удаленных сайтов, где присутствует возможность разместить php код или для импорта в webview мобильных приложений.

# Обязательная информация перед настройкой

  1. KClient PHP подключается исключительно на сайты, которые находятся на сторонних хостах или серверах. Не добавляйте код KClient PHP на сайт или webview, которые загружены как локальный лендинг или оффер в Keitaro;

  2. Ссылка кампании (tracking link) при работе с KClient PHP — это ссылка на сайт, на который добавляется трекинг—код из кампании трекера. Путь трафика при работе с KClient PHP: сайт с трекинг—кодом -> Keitaro -> выполнение действий и настроек кампании, из которой взят трекинг—код;

  3. Расширение файла, в который добавляете код интеграции обязательно .php;

  4. Домен, припаркованный к Keitaro, и домен сайта, на который ставите трекинг—код - это обязательно два разных домена с активным SSL—сертификатом (оба работают по HTTPS);

  5. Не добавляйте в поток кампании трекера ссылку на сайт, на который ставите код KClient PHP. Пример: ставим код KClient PHP на сайт mysite.com -> запрещено добавлять ссылку mysite.com в поток кампании трекера, т.к. это нарушает корректную логику настройки схемы и вызывает бесконечный редирект.

# Подключение и настройка

  1. Создание кампании

Создайте кампанию в Keitaro.

Пример настройки кампании: созданы два потока. Первый поток с действием Ничего не делать и фильтром БОТ. Данный поток фильтрует и оставляет ботов на сайте, где подключен KClient PHP. Нет необходимости добавлять bot page в кампанию.

Второй поток создается с необходимыми фильтрами для целевого трафика. В поток добавляются целевые офферы для сбора конверсий.

Допустимо добавлять любые типы потоков, лендингов, офферов, фильтров и т.д. Все зависит от воронки трафика.

  1. Получение трекинг—кода

Выберите домен с HTTPS на вкладке Настройки кампании. Перейдите во вкладку Tracking и скопируйте трекинг—код (код для лендинга):

  1. Подключитесь по SFTP

Перейдите в директорию сайта:

Вставьте в index.php сайта, начиная с первой строки (до <html> и DOCTYPE), трекинг—код, скопированный из кампании:

Проверка кодировки UTF-8.

Убедитесь, что кодировка index.php сайта UTF-8, без BOM.

Воспользуйтесь обычным текстовым редактором:

  1. Скачивание файла клиента

Файл kclient.php — это клиент, на который ссылается трекинг—код и который вызывает кампанию трекера.

Скачайте файл kclient.php на вкладке Tracking

Загрузите файл рядом с файлом index.php, куда вставляли код интеграции. Файл kclient.php загружайте с таким именем. При загрузке файла с другим именем обязательно переименовать на идентичное в трекинг—коде.

Основной этап интеграции завершен. При переходе на главную страницу сайта, в index.php которой добавили трекинг—код, выполняются действия из кампании Keitaro, из которой копировался трекинг—код.

# Тестирование

Откройте сайт, затем смотрите лог трафика. В логе отображается клик и действие, которое выбрано для клика в потоке (Редирект на оффер, Do nothing и т.д.)

Подробно о том, почему клик пошел на определенный поток.

Включение лога.

Если ранее не пользовались логом трафика, включите лог и откройте сайт еще раз.

# Получение, запись и передача URL параметров (меток) с сайта

Пошаговая инструкция на примере KClient PHP

# Отправка postback

  1. Добавьте следующий код на index.php.
$_SESSION['subid'] = $client->getSubid();
1

Код записывает ID клика Keitaro в сессию.

  1. На странице, при открытии которой фиксируется целевое действие (страница Спасибо), добавьте следующий код:
session_start();
var_dump($_SESSION);
$url = 'POSTBACK_URL/postback?payout=100&status=sale&subid=' . urlencode($_SESSION['subid']);
file_get_contents($url);
1
2
3
4

Перейдите в раздел Обслуживание-Postback URL Keitaro. Копируйте ссылку до /postback. Замените в ссылке.

Конструкция отправляет postback по адресу Postback URL.

# Переход на оффер кампании по кнопке на сайте

Если необходимо выполнять переход на целевую страницу нажатием кнопки на сайте, следуйте инструкции:

  1. Создайте поток в кампании Keitaro, схема Лендинги или Офферы. Добавьте в поток целевой оффер;

  2. Закоментируйте участок кода // $client->executeAndBreak();

  3. Создайте в index.php ссылку на оффер, используя переменную трекера $client->getOffer()

<?php
require_once dirname(__FILE__) . '/kclient.php';
$client = new KClient('https://domain_tracker/api.php?', 'wzbfwg3dxlmttkvt5v63mbw3x');
?>
<html>
...
<body>
<a href="<?php echo $client->getOffer() ?>">CLICK TO GO</a>
</body>
</html>
1
2
3
4
5
6
7
8
9
10

Переход на конкретный оффер по конкретной кнопке на сайте:

Используйте конструкцию $client->getOffer(array('offer_id' => ID)):

<a href="<?php echo $client->getOffer(array('offer_id' => 123));?>">CLICK TO GO</a>
1

Где ID - это ID оффера в потоке

Если присутствует вероятность, что трекер не вернет оффер, выставьте ссылку по умолчанию вторым параметром:

<a href="<?php echo $client->getOffer(null, 'https://ya.ru');?>">LINK</a>
1

# Вывод subid клика Keitaro на сайте и передача далее

Если необходимо забирать subid и передавать дальше (в партнерскую сеть или CRM), без отправки postback скриптом трекера - добавьте метод $client->getSubid(); в код KClient PHP

Выведите subid на форме заявки как <input type="hidden" name="subid" value=<?echo "$subid"?> />

Настройка со стороны трекера закончена. Дальше передаете subid c формы на обработчик (если это необходимо), как <form action="call.php" method="post" >, либо воспользоваться любым другим способом взятия со страницы и передачи дальше метки, подходящим для партнерки/CRM, в которую необходимо передать subid клика и отправить postback в трекер.

# Показ HTML (баннеров) в определенных местах на сайте

KClient PHP используется для встраивания баннеров в код сайта, на который добавляется трекинг—код. Для показа баннера в определенном месте сайта:

  1. Удалите (закомментируйте) в трекинг-коде строки:
$client->execute();`
1

и

$client->executeAndBreak();
1
  1. Добавьте в трекинг—код:
$GLOBALS['client'] = $client;
1
  1. Вставьте код в index.php или необходимой второстепенной страницы сайта:
<?php echo $GLOBALS['client']->getContent() ?>
1

# Как добавить на второстепенную страницу сайта

  1. Выполните инструкцию по подключению клиента из раздела Подключение и Настройка;

  2. Подключите KClient PHP на внутренней странице, добавив $client->restoreFromSession(); :

<?php
require_once dirname(__FILE__) . '/kclient.php';
$client = new KClickClient('http://domain_tracker/api.php?', 'token');

$client->restoreFromSession();
1
2
3
4
5

Можете вызывать необходимые методы, но без создания нового клика, например, вызов оффера c второстепенной страницы:

<a href="<?php echo $client->getOffer()">offer link</a>

# Методы KClient PHP

Метод Описание
$client->sendAllParams() Передача параметров из адресной строки
$client->forceRedirectOffer() Если в потоке выбран оффер, то выполнить редирект на данный оффер. В ином случае, необходимо использовать getOffer()
$client->params('param1=c&param2=b') Передача строки параметров
$client->param('extra_param_5', '123') Альтернативный способ передачи параметра
$client->sendUtmLabels() Передача из адресной строки utm—меток
$client->debug() Показ отладочной информации
$client->currentPageAsReferrer() Отправить адрес текущей страницы в качестве реферера
$client->keyword('QUERY') Использование значения QUERY в качестве ключевика
$client->execute() Выполнение инструкций Keitaro и с продолжением выполнения кода страницы
$client->executeAndBreak() Выполнение инструкций Keitaro с остановкой выполнения страницы. Если передано действие в потоке «Do nothing», остановки не произойдет
$client->getOffer() Получение ссылки на оффер. В кампании должен присутствовать поток со схемой Офферы, иначе получите результат no_offer
$client->getBody() Получение содержимого body
$client->getHeaders() Получение заголовков (headers)
$client->isUnique(TypE) Статус уникальности (варианты TYPE: flow, campaign, global)
$client->isBot() Статус бота
$client->disableSessions() Отключение куки PHP—сессии (без данной куки restoreFromSession не работает)
$client->restoreFromQuery() Ловит параметры _subid и _token из запроса и не заводит нового клика
$client->restoreFromSession() Восстанавливает предыдущее посещение из сессии и не заводит нового клика

# Отладка

Пошаговый гайд о причинах и способах исправления проблем в настройке и работе KClient PHP.

# Расшифровка ошибок

  • [REQ_ERR: 400] — запрос не удалось обработать из-за синтаксической ошибки.
  • [REQ_ERR: 402] — не соответствует типу редакции или лицензия закончилась.
  • [REQ_ERR: 401] — запрос требует аунтефикации пользователя.
  • [REQ_ERR: 403] — доступ к указанному ресурсу ограничен.
  • [REQ_ERR: 404] — сервер не нашел по указанному URI никаких ресурсов.
  • [REQ_ERR: 405] — указанный метод не применяется к текущему ресурсу.
  • [REQ_ERR: 407] — необходима авторизация на прокси-сервере.
  • [REQ_ERR: 408] — превышено время ожидания запроса.
  • [REQ_ERR: 410] — требуемый ресурс больше недоступен на сервере и адрес расположения неизвестен.
  • [REQ_ERR: 429] — аномально много запросов.
  • [REQ_ERR: 500] — внутренняя ошибка сервера.
  • [REQ_ERR: 501] — сервер не поддерживает функциональных возможностей, необходимых для выполнения запроса.
  • [REQ_ERR: 502] — сервер, выступая в роли шлюза или прокси-сервера, получил некорректный ответ от сервера.
  • [REQ_ERR: 503] — сервер не обрабатывает запрос из-за временной перегрузки или технических работ.
  • [REQ_ERR: 504] — сервер, выступая в роли шлюза или прокси-сервера, не дождался в рамках установленного таймаута ответа от вышестоящего сервера текущего запроса.
  • [REQ_ERR: UNSUPPORTED_PROTOCOL] — переданный URL содержит неподдерживаемый библиотекой cURL протокол.
  • [REQ_ERR: FAILED_INIT] — проблема при инициализации запроса.
  • [REQ_ERR: BAD_URL] — неправильно сформирован URL.
  • [REQ_ERR: COULDNT_RESOLVE_PROXY] — проблема при определении прокси.
  • [REQ_ERR: COULDNT_RESOLVE_HOST] — проблема при определении сервера у домена: проверьте DNS.
  • [REQ_ERR: COULDNT_CONNECT] — сбой при соединении с сервером.
  • [REQ_ERR: PARTIAL_FILE] — переданы не все данные: проверьте системный лог трекера.
  • [REQ_ERR: READ_ERROR] — ошибка чтения данных.
  • [REQ_ERR: OUT_OF_MEMORY] — недостаточно памяти.
  • [REQ_ERR: OPERATION_TIMEDOUT] — превышен лимит ожидания ответа трекера: проверьте, что сервер, где стоит KClient PHP, подключается к трекеру без ошибок.
  • [REQ_ERR: HTTP_POST_ERROR] — ошибка при HTTP—запросе.
  • [REQ_ERR: BAD_FUNCTION_ARGUMENT] — функция вызвана с неправильными параметрами.
  • [REQ_ERR: TOO_MANY_REDIRECTS] — аномально много переадресаций, достигнут счётчик разрешённых переадресаций.
  • [REQ_ERR: GOT_NOTHING] — сервер отправил пустые данные.
  • [REQ_ERR: SEND_ERROR] — сбой при отправке данных.
  • [REQ_ERR: RECV_ERROR] — сбой при получении данных.
  • [REQ_ERR: BAD_CONTENT_ENCODING] — нераспознанная кодировка данных.
  • [REQ_ERR: SSL] — проблемы с SSL: проверьте настройки Cloudflare (секция SSL).
  • [REQ_ERR: UNKNOWN] — неизвестная ошибка: проверьте логи трекера.

# KClient PHP FAQ

Почему показывает ошибку 500 или белую страницу?

Добавьте перед кодом интеграции, после <?php:

ini_set('display_errors', 'on');
error_reporting(7);
1
2
Как взять subid на внутренних страницах сайта?

Содержимое 'sub_id' сохраняется в сессию:

$_SESSION['sub_id'];

Пример использования:

session_start();
...
$data = array(
 'sub1' => $_SESSION['sub_id'],
 'name' => $_POST['name'],
  ...
);
1
2
3
4
5
6
7
Как оставить определенных пользователей на сайте?

Используйте "Do nothing" в качестве действия потока.

Почему в браузере ошибка TOO_MANY_REDIRECTS?

Вероятнее всего, трекинг-код стоит на локальном лендинге в Keitaro. Смотрите раздел Важно в начале страницы.

Почему в логе трафика http-редирект, но по факту не происходит?

Причина в том, что файл index.php сохранён в UTF-8 с заголовком BOM.

Как выявить: убедитесь, что перед кодом нет пробела или любого другого символа. Как исправить: удалите символ. Если не получится, сохраните заново в UTF-8 без BOM.

Внимание

Не все редакторы видят символ.

Проверка ботов на сайте
/*
Трекинг-код (код для лендинга)
*/
if ($client->isBot()) {
   echo 'bot';
} else {
   echo 'not bot';
}
1
2
3
4
5
6
7
8

TIP

Чтобы отключить запись кликов ботов в статистику, выключите в потоке опцию "Подсчет кликов".

Как подключить к Wordpress?

Смотрите плагин WordPress.

Как передать title в качестве ключевой фразы?

Необходимо взять title в PHP cкриптах. Передается keyword с помощью метода $client->keyword('...'):

$client->keyword($myTitle);`
1

$myTitle — это пример того, как содержимое переменной передаётся в качестве keyword.

Как указать путь до KClient.php, если сайт не в корне?

Посмотрите директорию сайта и указывайте абсолютный путь:

require '/путь_до_сайта/kclient.php';
1