Promotion tool

Keitaro

Keitaro is a self-hosted tracker. It runs on a server you operate, and the clicks stay in that install. A campaign has a link on your domain. Streams inside the campaign, also called flows, decide which visitors see a landing page, which visitors go straight to an offer, and which visitors are filtered out. The identifier Keitaro gives each click is the subid. This article explains how to pass that subid into a Maxlead tracking link and how the network postback sends the conversion back to the same install.

Maxlead is a CPA performance network that has operated since 2015. Keitaro is a separate product. Nothing in the tracker account approves you for an offer, and nothing in the publisher account hosts your Keitaro server. You open a Maxlead account, take a tracking link that already carries your publisher id, and use Keitaro when you want filters and landing pages in front of that link. Payable conversions are still the approved ones on the network, paid weekly. If a Keitaro label on your version differs, use the label in your install.

Who it is for

Keitaro is for publishers who want campaign logic on their own server: filters by country or device, several landing pages, and a click id they can see in the local log. Media buyers use the filters so a stream only accepts the traffic they meant to buy. People who host their own landing pages use it so the page and the click live in one place. It is the wrong choice if you do not want to maintain a server. A campaign URL on a stopped server does not record a subid, and it does not forward the visitor to the tracking link.

Filters are not a substitute for the offer’s rules. The offer on Maxlead must allow the country and the source. A Keitaro filter can drop a country you did not want to buy. It cannot make a forbidden country payable, and it cannot make a forbidden source acceptable. Set the filter to match the offer, not to widen it. If the filter lets a country through that the offer does not list, those visits never become clicks on the offer.

Keep the two reports apart in your head. Keitaro shows streams, filters, landing pages, and the subid. The network dashboard shows clicks, conversions, earnings, EPC, and CVR. Earnings are approved payout. CVR is approved conversions divided by clicks. EPC is earnings per click. Pending conversions do not appear in the reports that count for you, and they are not part of the weekly payout. Rejected conversions are not paid as if they were approved.

Campaigns, filters, and landing pages

A campaign starts with a traffic source, so the parameters that source passes have names you can filter on. The campaign link is what the ads use. Inside it, streams run in order. Each stream has filters, a schema, and one or more landing pages and offers. Filters decide who may enter the stream. A country filter, a device filter, or a parameter filter can be combined. With an “and” relation, the click must meet every condition. A stream with no matching click falls through to the next stream, or out of the campaign, depending on how you ordered them.

The offer on a stream is the outbound URL. That URL should be the tracking link from the offer, with Keitaro’s {subid} written into a sub ID. A landing page can be a redirect to a page you host, or a page stored in Keitaro. Either way, the action that should reach the advertiser has to go through the campaign’s offer link so the subid is still attached. A button that points at the advertiser preview leaves the subid behind on your server.

Direct the first test to the offer with a simple filter and no landing page. You are checking that the subid leaves the server and comes back. Add a landing page after that click is proven, and give it a stream you can separate in the report. Name the stream after the country and the creative. A filter that silently drops half the clicks will look like a low conversion rate if you never check how many clicks the filter refused.

Pass the subid into the tracking link

Copy the tracking link from Maxlead once the publisher account may run the offer. Public offers can be copied after the account is approved. Offers that require approval stay closed until the request is approved. pid is already on the link. Paste the link into the offer URL in Keitaro and add the sub IDs. Do not rebuild the link by hand.

Keitaro’s click id token is {subid}. Put it in s1. Put the traffic label in s2 and the creative label in s3. Maxlead stores s1 through s8 and can return them on the postback. It also creates its own click id, available as {click_id}. That value identifies the click in Activity. It does not identify the click in Keitaro. The postback must send the subid back, which means it must send the contents of s1, via {sub1}. If you replace {subid} with a word, every visitor collapses into one value and Keitaro cannot attach a conversion to a single click.

The traffic source’s own click id is another field, often mapped as an external id, and it is what you would use if Keitaro itself sends a postback onward to the ad platform. That outgoing postback is configured on the source or on the campaign’s S2S tab. It is not the URL you paste into the network. The network calls Keitaro. Keitaro may then call the source. Mixing those two URLs is how a test appears to “lose” conversions that were approved.

How the network postback returns the conversion

The network fires a postback on approval and on rejection. It does not fire one for a conversion that is still pending. Use a global postback when the whole account should call the same Keitaro URL. Use an offer postback when one campaign should call a different URL. The offer postback replaces the global one for that offer. The address has to be the postback URL your Keitaro install shows, on a domain that reaches the server.

Keitaro matches the conversion with the subid parameter. Set subid to {sub1}. Set payout to {payout} if you want the amount the network reports, in dollars with two decimals. The network’s status token is {status}, and the only values are approved and rejected. Keitaro has its own status names. Before you pass {status} straight through, check which words your install counts as a conversion you care about. Do not mark revenue when the network status is rejected. You can also send {offer} and {sub2} through {sub8} as extra detail. They do not replace the subid.

Send a real visitor through the campaign link. Confirm the click in Keitaro, with a subid, and the click in Activity, with s1 holding that same subid, s2 and s3 holding your labels, and the country allowed. After approval, Keitaro should show the conversion on that subid. If Activity shows approved and Keitaro does not, the postback URL, the subid token, or the server’s response is wrong. Generating a conversion inside Keitaro by typing a subid proves the postback path only if that subid was produced by a real click that also hit the network.

Clicks, filters, and approved conversions

Keitaro can show more campaign hits than the network shows clicks. Some of those hits were filtered into a stream that does not go to the offer. Some reached the offer URL but from a country the offer does not accept, so they were not saved. Some never left a landing page. None of those are approved conversions. Read the stream report before you read CVR. A filter that rejects the country you are buying will make a good offer look dead.

Scale from approved conversions and from EPC, not from the number of rows in the click log. EPC is earnings per click on the dashboard, using approved earnings. CVR uses approved conversions. One hour is long enough to see whether the subid is passing. It is not long enough to decide that a stream should take the rest of the budget. Wait until approvals and rejections have had time to return, then compare the stream you meant to test.

When you increase traffic, leave the filter and the sub IDs alone. If you loosen a country filter, you are running a new test, and the offer has to allow the new country or the extra clicks will not be stored. If you change the landing page, put it on a stream you can name. Approved earnings, and only those, are what the weekly payout uses.

A worked example

This example requires an offer that allows the United States and allows native traffic. A filter set to the United States does not create that permission. If the offer forbids native, or omits the country, pick another offer or do not launch.

Create a traffic source for the native platform. Create a campaign and a stream whose filter accepts the United States and the devices you bought. Set the offer URL to the tracking link, with s1 set to {subid}, s2 set to us-native, and s3 set to headline-a. us-native names the source. headline-a names the first headline. Skip the landing page on this stream. Put the campaign link in the native campaign.

The visitor hits your server. The filter lets the click into the stream. Keitaro replaces {subid} and redirects to the tracking link with pid, s1, us-native, and headline-a. The network stores the click and sends the visitor on. The postback uses subid set to {sub1}, payout set to {payout}, and, once you have checked the status words, the network status. On approval, Keitaro attaches the conversion to that subid and stores the payout it received.

In the network report, filter or group by the sub IDs. us-native and headline-a should line up with clicks, approved conversions, EPC, and CVR. In Keitaro, the same stream should show the clicks that passed the filter and the conversions that the postback returned. A stream with clicks and no network clicks means the offer URL or the country is wrong. A network approval with no Keitaro conversion means the subid did not come back.

Mistakes

Traffic sent to the advertiser preview never picks up your publisher id. The preview is for reading the page, including from a landing page you are about to host. The stream’s offer URL has to be the tracking link. A landing page button has to reach that URL through the campaign, not around it. Otherwise the subid sits in Keitaro with no network click to approve.

Rewriting the subid breaks the match in a quiet way. The token {subid} has to remain until Keitaro fills it. Do not paste an old subid into the offer URL, do not trim the value, and do not send {click_id} back into the subid parameter. {click_id} is the network’s id. Keitaro is looking for its own. If s1 is the slot you chose, the postback parameter subid is {sub1}. Pointing it at {sub3} sends headline-a, and headline-a is not a click.

One hour of filtered traffic is a small, biased sample. The filter may have dropped the clicks you thought you bought. The advertiser may not have approved anyone yet. Look at clicks that reached the network, then at approved conversions, then at EPC and CVR. A stream that looks fast in Keitaro can still be a stream the offer has not paid.

A forbidden country or source is outside the filter’s power to repair. us-native is an honest label only when native and the United States are allowed. If your filter is wider than the offer, the extra countries inflate Keitaro and vanish on the network. If the source is forbidden, approvals will not follow a clean subid. Stop the campaign when the offer is paused. The server will keep taking clicks for as long as the ads stay on.

Open a publisher account, then point the stream

Keitaro can filter and store the subid only after there is a tracking link to put in the offer URL. Open a publisher account from the Maxlead homepage, choose an offer that allows the country and the source, and place {subid} in s1 with labels such as us-native and headline-a. Save a postback that returns {sub1} as the subid and {payout} as the amount. Run a short test, compare the stream with approved conversions, and scale only the stream that matches. The server holds the click. The network decides the status and pays approved earnings on the weekly cycle.