Integration
Integration is the process of attaching an Adspect stream to your traffic flow, be it for active filtering or passive statistics collection. You will need a server (hosting) with PHP 5.6+ language support and enabled php-curl and php-json PHP extensions.
After creating a stream you will be immediately brought to the integration page. This page may also be accessed using the Code button next to each stream’s name in the list of streams.
Adspect supports three types of integration that differ in technical details and use cases:
Forward PHP integration via a standalone
index.php
file;Reverse PHP integration via including a
filter.php
file;JavaScript integration via
<script>
HTML tag embedding using a remoteajax.php
file.
All three integration types employ a special PHP file that is tied to a particular stream in the system. This file communicates with Adspect cloud in real time and performs traffic filtering.
Note
Adspect PHP files do not contain stream settings. You may change any stream settings at any time, and these changes will be picked up on the fly, i.e. you do not need to replace our PHP files after making changes.
PHP Integration
PHP integration comes in two flavors: forward and reverse. The only difference between them is how our PHP files are wired with your locally hosted landing pages, i.e. which file receives incoming traffic. Both flavors are equally secure otherwise. Choose whichever is more convenient for you.
Forward PHP Integration
In forward PHP integration filtering is done by a special index.php
file that you place in your landing page directory
or elsewhere accessible via HTTP. This file acts as an entry point for web traffic and is wired to our servers that
process clicks and make decisions.
After uploading the index.php
file to your hosting its URL will be the cloaked URL suitable for use in advertising campaigns.
Several copies of the same index.php
file may be used for protecting several offers or landing pages without interfering
with each other.
Reverse PHP Integration
There’s also a slightly different reverse PHP integration that uses a filter.php
file which is included into your
PHP page file (normally your safe page) via a single line of PHP code. Traffic lands directly on this page, our code
in the filter.php
file inspects it and chooses either to keep the visitor on the page or display a different one.
In order to perform reverse PHP integration you first need to download the filter.php
file on the Reverse PHP Integration
tab and put it into the folder of your site or landing page. Several copies of the same filter.php
file may be used for
protecting several sites or landing pages without interfering with each other.
Then add the following code as the first line (before all other code) of your site or landing page index file (usually
named index.php
) above all other code:
<?php require __DIR__ . '/filter.php' ?>
If you added the code into your safe page, then specify No Action for a safe page action in stream settings. Adspect will not take any action, leaving the visitor on their current page which is the safe page.
Likewise, if you added the code into your money page, then specify No Action for your money page in settings.
Tip
If your site is written in pure HTML, then you may safely change the extension of your file from .html
to .php
before adding our line of code to it.
Once set up, direct traffic to the page you added the code into.
WordPress and Other CMS
Reverse PHP integration is useful for integrating Adspect into sites based on WordPress or similar CMS (content management systems.)
WordPress has a file named index.php
in its
root directory.
That is the file where you should add that single line of PHP code discussed above:
<?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
*/
…
Place the filter.php
file into the same folder.
Since integration is performed into the root script of WordPress, it means that Adspect code will be executed when any site page is visited.
If WordPress is your safe page, then set safe page action to No Action and leave page field empty;
if WordPress is your money page, then set money page action to No Action and leave page field empty.
Important
Make sure that any WordPress caching plugins are disabled. If your clicks do not appear in stream’s click log, then it often indicates that WordPress serves its pages from cache, so you must disable it.
Warning
WordPress updates will overwrite its index.php
file, thereby removing our integration code. If your WordPress-based stream suddenly
stopped registering clicks in Adspect reporting, then the likely cause is recent WordPress update, and you should redo integration.
We recommend disabling automatic WordPress updates.
Getting Scan Status
When transferring control to other PHP files or doing reverse PHP integration into them, you may obtain
scan status information about each click using the $_adspect
global PHP variable. It contains an associative
array of the following structure:
{
"cid": "fd808d23604d84fbc5e81d7b954c4f9a",
"ok": true,
"js": false,
"action": "local",
"target": "page.php?utm_campaign=test"
}
The fields are:
Key |
Description |
---|---|
|
Unique Adspect internal click ID, string (will be the same for both stages of click processing.) |
|
Whether the click was determined legitimate, boolean. |
|
Whether JS fingerprinting code must be served, boolean (will always be |
|
Action performed for the visitor, string (will normally be either |
|
Target for the action performed (URL, file path, code), string. |
JavaScript integration
JavaScript integration is meant to be used with third party services like Shopify, Blogspot, or Tilda, where you cannot upload custom PHP files to do PHP integration. Traffic flow is much like in reverse PHP integration: visitors come to the safe page first, then legitimate ones are displayed the money page whereas moderators and bots are left where they are.
You will also need to download a PHP file called ajax.php
and host it somewhere, but its final location does not
matter as it will be linked into the safe page using a <script>
HTML tag.
Important
Always use HTTPS URL of the ajax.php
file if the website you are integrating Adspect into also uses HTTPS (which is
almost always the case.) Trying to link ajax.php
to an HTTPS site via plan HTTP URL will result in
mixed content error in most modern browsers,
and cloaking will not work.
Note
Safe page settings are ignored in JavaScript integration because visitors initially land on the safe page, which is the page
that the integration <script>
tag is placed on.
Switching Streams
Each stream has its own index.php
, filter.php
, and ajax.php
files wired to it that have the stream ID encoded inside.
However, you may override that encoded stream ID and send a click to a different stream by putting the destination stream ID
into the __sid
URL parameter, e.g:
https://example.com/index.php?__sid=1ea85c7c-b977-6804-8e69-00162501c2b4
You may find stream ID next to its name in the streams list.
If you need use a different parameter name instead of __sid
, then open Adspect PHP file in a text editor and replace
the __sid
string with the desired name (e.g. utm_campaign
.)
If you are using URL parameters passthrough to your money or safe page, then you may want
to remove the __sid
parameter from the final URL with a DELETE
URL rule.