Интеграция

Интеграция — это процесс подключения потока Adspect к трафику.

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

Примечание

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

PHP-интеграция

PHP-интеграция представлена в двух видах: прямая и обратная. Они различаются способом взаимодействия наших фильтрующих файлов и ваших локально размещенных страниц, если они есть. Иначе говоря, различие в том, какой из файлов принимает входящий трафик. В остальном оба вида равнозначны по уровню безопасности. Выбирайте тот, который вам более удобен.

Прямая PHP-интеграция

В прямой PHP-интеграции разделение трафика осуществляется при помощи специального файла index.php, который вы размещаете в папке лендинга или в любом другом месте, доступном по протоколу HTTP. Этот файл выступает в роли точки входа для вашего трафика и работает в паре с нашими серверами, которые уже непосредственно принимают решения.

После загрузки файла index.php на хостинг ссылка на него и будет «заклоаченной» ссылкой для использования в рекламе. Несколько одинаковых файлов index.php могут использоваться параллельно для защиты нескольких офферов или лендингов, при этом не мешая друг другу.

Обратная PHP-интеграция

Также имеется немного отличающаяся обратная PHP-интеграция, в которой используется файл filter.php. Этот файл подключается напрямую к вашей PHP-странице (обычно к белой странице) при помощи одной строчки PHP-кода. Трафик приходит напрямую на эту страницу, наш код из файла filter.php проверяет его и отправляет целевых посетителей далее на контент, а модераторов и ботов оставляет на белой странице.

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

Затем добавьте следующий код первой строчкой в индексный файл вашего сайта или лендинга (обычно называется index.php) над всем остальным кодом:

<?php require __DIR__ . '/filter.php' ?>

Совет

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

Если вы добавили код в файл вашей белой страницы, то в настройках потока оставьте поле белой страницы пустым и укажите действие «Без действия» для белой страницы. Adspect не будет предпринимать никаких действий и оставит посетителя на текущей странице, которая и является белой.
Аналогично, если вы добавили код в контент-страницу, то в настройках потока оставьте поле контента пустым и укажите действие «Без действия» для контента.

После настройки просто направьте трафик на ту страницу, в которую вы добавили код.

WordPress и другие CMS

Обратная PHP-интеграция удобна для интеграции Adspect в сайты, построенные на WordPress или других подобных CMS (content management system).

WordPress имеет файл index.php в корневой папке. Именно в этот файл вам и нужно вставить строчку кода, как было описано выше:

Добавление кода в WordPress в корневой файл index.php

<?php require __DIR__ . '/filter.php' ?>
<?php
/**
 * Front to the WordPress application. This file doesn't do anything, but loads
 * wp-blog-header.php which does and tells WordPress to load the theme.
 *
 * @package WordPress
 */
…

Разместите наш файл filter.php рядом в той же корневой папке.

Так как интеграция производится в корневой файл WordPress, то код Adspect будет срабатывать при переходе на любую страницу сайта.

Если WordPress является белой страницей, то укажите действие «Без действия» для белой страницы, а поле страницы оставьте пустым;
Если WordPress является контентом, то укажите действие «Без действия» для контента, а поле страницы оставьте пустым.

Важно

Убедитесь, что любые кэш-плагины в WordPress отключены. Если вы не видите ваших переходов в статистике потока, то это обычно означает, что WordPress кэширует страницы и тем самым нарушает работу Adspect; отключите кэширование.

Предупреждение

При обновлении WordPress перезапишет файл index.php, тем самым удалив код интеграции, и ее придется выполнить заново. Мы рекомендуем отключить автоматическое обновление WordPress.

Статус сканирования

При передаче управления в другие PHP-файлы или при обратной PHP-интеграции в них вы можете получить информацию о статусе сканирования каждого перехода из глобальной PHP-переменной $_adspect. В ней содержится ассоциативный массив следующей структуры:

<?php
array(
  'cid' => 'fd808d23604d84fbc5e81d7b954c4f9a',
  'ok' => true,
  'js' => false,
  'action' => 'local',
  'target' => 'page.php?utm_campaign=test'
)

Значение элементов массива:

Элемент	Описание
`cid`	Внутренний уникальный идентификатор перехода, строка (будет одинаковым на всех этапах обработки перехода).
`ok`	Был ли переход посчитан целевым, логический.
`js`	Требуется ли отдать посетителю код сбора JS-отпечатка, логический (всегда будет иметь значение `false`, так как сбор отпечатков происходит до того, как управление будет передано в ваш код).
`action`	Действие, выполненное для этого перехода, строка (обычно или `local`, или `noop`).
`target`	Цель для выполненного действия (URL, путь к файлу, код), строка.

Скрытые URL-параметры

Иногда бывает необходимо передать в Adspect URL-параметр, которого физически нет в ссылке. Например, при работе нескольких рекламных кампаний через один поток удобно их разделять по sub ID, но не всегда желательно открыто его указывать в рекламной ссылке. Это легко решается при обратной PHP-интеграции путем добавления нужного параметра в суперглобальный массив $_GET перед вызовом кода Adspect:

<?php
$_GET['subid'] = 'hidden';
require __DIR__ . '/filter.php';

В этом примере Adspect увидит параметры ссылки так, как будто в них содержался параметр subid=hidden.

JavaScript-интеграция

JavaScript-интеграция предназначена в первую очередь для использования со сторонними сервисами, такими как Shopify, Blogspot или Tilda, где вы не имеете возможности загрузить PHP-файл для PHP-интеграции. Схема прохождения трафика аналогична обратной PHP-интеграции: посетители сначала попадают на белую страницу, нежелательные на ней и остаются, а целевым показывается контент.

Вам также потребуется загрузить и разместить на сервере наш PHP-скрипт ajax.php, но его конкретное расположение не имеет значения, так как файл будет подключен к белой странице через HTML-тег <script>.

Важно

Всегда указывайте HTTPS-ссылку при подключении файла ajax.php, если сайт, с которым вы делаете интеграцию, работает по протоколу HTTPS (подавляющее большинство современных сайтов использует HTTPS). Попытка подключить ajax.php к HTTPS-сайту при помощи обычной HTTP-ссылки приведет к ошибке mixed content (смешанное содержимое), и клоакинг не будет работать.

Примечание

Настройки белой страницы потока игнорируются при JavaScript-интеграции, т.к. посетитель изначально попадает на белую страницу — ту страницу, на которой размещен тег интеграции <script>.

Смена активного потока

У каждого потока есть связанные с ним файлы index.php, filter.php и ajax.php, в которых закодирован ID потока. Однако, вы можете изменить целевой поток для любого перехода, указав ID потока в параметре ссылки __sid:

https://example.com/index.php?__sid=1ea85c7c-b977-6804-8e69-00162501c2b4

Вы можете найти ID потока рядом с его именем в списке потоков.

Если вам нужно изменить имя параметра __sid на другое, то откройте PHP-файл Adspect в текстовом редакторе, найдите в нем строку __sid и замените ее на нужное вам имя (например, utm_campaign).

Если вы используете проброс URL-параметров в ссылку контента или белой страницы, то вы можете удалить параметр __sid из итоговой ссылки при помощи URL-правила DELETE.