# KClient PHP

advanced expert team enterprise

KClient PHP is the traffic tracking, and target-action checking method on the third-party sites. It connects Keitaro to remote resources via PHP—code. When you click on a site link, it performs actions and settings of the campaign which you connect to the site. Optionally, it performs a dynamic content spoofing without the visible redirect.

The method is suitable for any remote sites with the possibility to place php—code or to import mobile applications into webview.

WARNING

Important

  1. KClient PHP is only attached to the sites that are hosted on the third-party hosts or servers. Do not add KClient PHP code to a site or webview that is loaded as a local landing page or offer in Keitaro.

  2. When working with KClient PHP, the campaign tracking link is a link to the site, where the tracking code from the Keitaro campaign is added. The traffic path on working with KClient PHP: a site with a tracking code -> Keitaro -> execution actions, and settings of the campaign, from which the tracking code is taken.

  3. The file for adding the integration code must have php extension.

  4. The domain parked to Keitaro and the domain of the site, where you put the tracking code, must be two different domains with an active SSL-certificate (working on HTTPS).

  5. Do not add a link to the website, where the KClient PHP code is installed, in the campaign tracker's flow. For example, if you are placing the KClient PHP code on mysite.com, you must not add the mysite.com link to the campaign tracker's flow.

# Connection and setup

  1. Firstly, you must create a campaign in Keitaro.

The example of campaign setup: create two flows. The first flow with the Do nothing action and the BOT-Yes filter. This flow accepts bots and Do nothing action leaves them on the site (bot page), where KClient PHP is connected.

The second flow is created with the necessary filters for target traffic. Target offers are added to the flow to collect conversions

It is acceptable to add any type of flows, landing pages, offers, filters, etc. It all depends on your traffic funnel.

  1. Getting a Tracking Code

Select a domain with HTTPS on the Campaign Settings tab. Go to the Tracking and copy the tracking code (landing code):

  1. Connect via SFTP.

Go to the site directory

Insert the tracking code in index.php of the site, copied from the campaign. Starting from the first line (before <html> and DOCTYPE),

::: Check the UTF-8 encoding.

Make sure the site index.php is UTF-8 encoded, not BOM.

Use any text editor:

:::

  1. Downloading the kclient.php file.

The kclient.php file is the client, which the tracking code refers to and which calls the tracker's campaign.

Download the kclient.php file from the Tracking tab

Upload the file in the same directory with index.php. Load the kclient.php file with kclient.php name. If you upload a file with a different name, be sure to rename it to an identical one in the tracking code.

The main stage of setting up is now completed. Now, when you go to the home page of the website, in the index.php you added the tracking code for, the actions from the Keitaro campaign running where the tracking code was copied.

# Testing

Open the site, check traffic log. The log shows the click and the action selected for the click in the flow (Redirect to offer, Do nothing, etc.)

TIP

If traffic log is turned off, you must turn it on and open the website again.

If there are no clicks in the traffic log, go to the Debugging section below on this page.

# Reсeiving, recording and passing further URL parameters (placeholders) from the site

Step-by-step instructions using KClient PHP as an example. Use EN subtitles, please.

# Sending postbacks

  1. Add the following code to the index.php
$_SESSION['subid'] = $client->getSubid();
1

The code will write the Keitaro's click ID to the session.

  1. On the page that opens with the target action (the "Thank you" page), add the following code:
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

Go to the Maintenance—Postback URL section in Keitaro. Copy the link up to /postback. Replace this part of the link.

The form sends the postback to the Postback URL.

# Transition to offer by click button on a site

To navigate to a landing page by clicking a button on the site, follow the instructions:

  1. Create a flow in a Keitaro campaign, the Landings or Offers scheme. Add a targeted offer to the flow;

  2. Comment out the line of code // $client->executeAndBreak();

  3. Create a link to the offerer in index.php, using the tracker variable $client->getOffer()


<body>
<a href="<?php echo $client->getOffer() ?>">CLICK TO GO</a>
</body>
</html>
1
2
3
4
5

To go to a specific offer on a specific button.

Use the $client->getOffer(array('offer_id' => ID)) option:

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

Where ID is the ID of the offer in the flow

If the tracker will not return the offer, set the second parameter by default:

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

# Output a subid on a page to pass further

To take the subid, and pass it somewhere else (for example, to affiliate network or CRM) without sending a postback by the tracker script — add the method $client->getSubid(); to your KClient PHP code

Put the subid on the order form as `<input type="hidden" name="subid" value=<?echo "$subid"?> />``

The configuration on the tracker side is completed. Next, pass subid from the form to the handler (if needed), like <form action="call.php" method="post" > or use any other method of capturing from the page and passing on the placeholder, suitable for affiliate networks or CRM, which you want to pass the subid and send to the postback in the tracker to.

# Display HTML (banners) in specific places on the site

KClient PHP is used to embedded banners in the code of the site, where the tracking code is added. For showing a banner in a certain place of the site, please, do the following:

  1. Remove (comment out) the lines in the tracking code:
$client->execute();`.
1

And

$client->executeAndBreak();
1
  1. Add to the tracking code:
$GLOBALS['client'] = $client;
1
  1. Insert the code in the index.php or to the secondary page of the site:
<?php echo $GLOBALS['client']->getContent() ?>
1

# How to set secondary pages of the site

  1. Follow the instructions from the section Connection and Setup for connecting KClient PHP to a site;

  2. Connect KClient PHP on the internal page by adding $client->restoreFromSession();

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

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

Now you may call the needed methods without creating a new click, for example, calling an offer on a secondary page:

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

# Methods

Method Description
$client->sendAllParams() Passing parameters from an address bar
$client->forceRedirectOffer() Enables redirects to offers. If offer is chosen in the flow, it will perform the redirection to it. In other case, you must use getOffer()
$client->params('param1=c&param2=b') Passing parameters string
$client->param('extra_param_5', '123') Alternative method of passing a parameter
$client->sendUtmLabels() Passing UTM—labels from the address bar
$client->debug() Displaying the debugging information
$client->currentPageAsReferrer() Send the current page address as a referrer
$client->keyword('QUERY') Using the "QUERY" value as a keyword
$client->execute() Executing Keitaro instructions with the continuation of the page code execution
$client->executeAndBreak() Executing Keitaro instructions with stoppage of the page execution. If the action "Do Nothing" is passed in the flow, the tracker won't stop for the page loading.
$client->getOffer() Returns the offer link. The campaign must contain flows with schema 'Offers'. In other case, you'll receive 'no_offer'. Use this method if you don't want to perform automatic redirect to an offer.
$client->getBody() Get 'body' value
$client->getSubId() Returns SubId
$client->getHeaders() Get 'headers' value (array)
$client->isUnique(level) Uniqueness (level variations: flow, campaign, global)
$client->isBot() Bot status
$client->disableSessions() Turns off PHP session (without it, the cookie restoreFromSession won't work)
$client->restoreFromQuery() Catches query params _subid and _token without creating new click
$client->restoreFromSession() Restores previous click data from session without creating new click

# Debugging

First, it is advisable to turn on debug mode.

How to turn on debug mode?

If there are no clicks, add to the end of the integration code:

$client->showLog();
1

After $client->execute() and $client->executeAndBreak().

This will show the debug info on the page.

# Error codes

  • [REQ_ERR: 400] - This response means that the server could not understand the request because of response.
  • [REQ_ERR: 401] - The client must authenticate first to get the requested response.
  • [REQ_ERR: 403] - The client does not have access rights to the content.
  • [REQ_ERR: 404] - The server cannot find the requested resource.
  • [REQ_ERR: 405] - The request method is known by the server, but has been turned off and cannot be used.
  • [REQ_ERR: 407] - The authentication is needed to be performed by a proxy.
  • [REQ_ERR: 408] - Request timeout.
  • [REQ_ERR: 410] - The requested content has been permanently deleted from the server, with no forwarding address.
  • [REQ_ERR: 429] - The user has sent too many requests in a given amount of time.
  • [REQ_ERR: 500] - The server has encountered a situation it doesn't know how to handle.
  • [REQ_ERR: 501] - The request method is not supported by the server and cannot be handled.
  • [REQ_ERR: 502] - The server, while working as a gateway to get a response needed to handle the request, got an invalid response.
  • [REQ_ERR: 503] - The server is not ready to handle the request. Common causes are that a server is down for maintenance or is overloaded.
  • [REQ_ERR: 504] - The server is acting as a gateway and cannot get a response in time.
  • [REQ_ERR: 505] - The HTTP version used in the request is not supported by the server.
  • [REQ_ERR: UNSUPPORTED_PROTOCOL] - The URL you passed used a protocol that this cURL does not support.
  • [REQ_ERR: FAILED_INIT] - Very early initialization failed. This is likely to be an internal error or problem, or a resource problem where something fundamental couldn't get done at initial time.
  • [REQ_ERR: BAD_URL] - The URL was not properly formatted.
  • [REQ_ERR: COULDNT_RESOLVE_PROXY] - The given proxy host could not be resolved.
  • [REQ_ERR: COULDNT_RESOLVE_HOST] - The given remote host was not resolved. Check DNS settings of the domain.
  • [REQ_ERR: COULDNT_CONNECT] - Cannot connect to the tracker. Check if the server with Keitaro installed is up.
  • [REQ_ERR: PARTIAL_FILE] - A data transfer was shorter or larger than expected. Check Keitaro system log.
  • [REQ_ERR: READ_ERROR] - There was a problem reading data.
  • [REQ_ERR: OUT_OF_MEMORY] - A memory allocation request failed. You must increase memory_limit on the client server.
  • [REQ_ERR: OPERATION_TIMEDOUT] - The specified time-out period was reached according to the conditions.
  • [REQ_ERR: HTTP_POST_ERROR] - Internal post-request generation error.
  • [REQ_ERR: BAD_FUNCTION_ARGUMENT] - A function was called with a bad parameter.
  • [REQ_ERR: TOO_MANY_REDIRECTS] - There's a case of infinite redirects.
  • [REQ_ERR: GOT_NOTHING] - Nothing was returned from the server.
  • [REQ_ERR: SEND_ERROR] - Cannot send data to the tracker.
  • [REQ_ERR: RECV_ERROR] - Failure with receiving network data.
  • [REQ_ERR: BAD_CONTENT_ENCODING] - Unrecognized transfer encoding.
  • [REQ_ERR: SSL] - SSL error. You must check Cloudflare settings (section SSL).
  • [REQ_ERR: UNKNOWN] - Unknown error. Check Keitaro logs.

# KClient PHP FAQ

Why does the page show status 500?

Add after <?php:

ini_set('display_errors', 'on');
error_reporting(7);
1
2

It must show the error message.

Why doesn't HTTP-redirect work?

The file index.php might contain a BOM header.

Search for Save UTF-8 without BOM in your editor.

How to integrate KClient PHP with WordPress?

Use WordPress plugin.

How to leave specific visitors on the site?

Replace

$client->execute();
1

With

$client->executeAndBreak();
1
How to send title as a keyword?

You need to learn how to get title in php scripts. You need to send the keyword with $client->keyword('...') method:

$client->keyword($myTitle);
1

$myTitle - is the example of how the variable content is transferred as a keyword.

How to leave specific users on the site?

Use action "Do Nothing" in the flow.

How to just check if visitor is a bot?

Use method $client->isBot(). Example:

if ($client->isBot()) {
   echo 'bot';
} else {
   echo 'not bot';
}
1
2
3
4
5
How to insert the path to kclient.php if there are folders?

Check your site directory and put an obsolete path:

require '/path_to_the_website/kclient.php';
1
How to get a subid on the secondary pages?

The subid content is saved into a session:

$_SESSION['sub_id'];

Please use the following piece of code in your scripts:

session_start(); // it's better to launch the session if it wasn't used earlier. 
...
$data = array(
 'sub1' => $_SESSION['sub_id'],
 'name' => $_POST['name'],
  ...
);
1
2
3
4
5
6
7
How to use Click Client on inner pages?

Enable Click Client on an inner page by adding $client->restoreFromSession(); :

<?php
require_once dirname(__FILE__) . '/kclient.php';
$client = new KClient('https://..../api.php?', 'TOKEN');

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

Paste the code to create an offer link:

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