1. Overview
2. Advertiser Types
3. Commission Rules
4. Item-Specific Commissions in Detail
5. Pixel Integration
5.3. Real-World Integrations
5.4. Additional Functionality
5.5. Testing Pixel Integration
5.6. Pixel Integration Problems
6. Common Phrases and Definitions
1. Overview
This document provides technical specifications to help guide your successful integration into the dynamic commissioning system. This includes required and optional information, and the format that information is expected to be in, with examples of implementation where appropriate.
There are two methods for automated uploading of new orders:
- Pixel: small HTML snippet which is generally placed on an order confirmation or "thank you" page after a successful transaction, and it sends the information into the dynamic commissioning system at that time (see section: 5. Pixel Integration).
- Bulk Upload: generally a daily upload of a CSV file, that will then be processed by the dynamic commissioning system (see section: Dynamic Tracking - Bulk Upload: New Orders).
Note that you will be able to bulk upload a CSV of corrected orders into the system. This is intended for returns, cancellations, payment issues, or whatever reason may exist for an order to change after it was added to the dynamic commissioning system (see section: Dynamic Tracking - Bulk Upload: Corrected Orders ).
No Personally Identifiable Information (PII) may be passed to Ascend. PII includes but is not limited to information which can be used to distinguish or trace an individual's identity, such as their name, social security number, email address, phone number, or physical address.
2. Advertiser Types
This is a brief introduction to different advertiser types. This is not technically needed for implementation, but we find it helps in communication.
2.1. Standard Advertiser
This type of advertiser logs all orders, or transactions, through Ascend. Tracking these transactions can be done from anywhere in the advertiser's website and does not require a specific "landing page".
2.2. Gateway Advertiser
This type of advertiser uses a URL with special parameters that are used to indicate the source of traffic and determine whether or not to display the pixel on the order confirmation page.
3. Commission Rules
Commission rules let advertisers have separate commission rates based on various data points available about the transaction. Examples would include leveraging item SKU information, publisher performance, or if the customer is a new or one that already exists in your system.
This allows fine-grained control over your commission pay-outs.
4. Item-Specific Commissions in Detail
Item-specific commissions let advertisers have separate commission rates for different products. First, a base or default commission rate is set, 10% for example. Now it is possible to create special commission rates. For example, an artificial Christmas tree company would increase commission for trees to 15% around Christmas to move more trees. Stands, lights, etc. will still earn 10% commission, but trees now generate 15% commission.
In order to have item specific commissions when using the Product List Condition, a flat text file with item lists containing item IDs needs to be created and hosted by the advertiser.
That text file must include the following pipe-delimited fields:
Item Name|Item ID|List ID
| Item Name | The unique item or product name associated with a specific payout. |
|---|---|
| Item ID | The unique item or product ID associated with a product. The item ID corresponds to the ITEM_ID(X) (ex: ITEM_ID1, ITEM_ID2) parameter of the tracking pixel or batch file. |
| List ID | The list ID associated with the product; one list ID may correspond with many products; list IDs are generated using the Ascend web interface by clicking "Partner Program Terms" under the "Manage Partners" drop-down menu. Next, click on "Manage Product Lists" (top right of the page); next to each list that is created, the list ID is displayed in parentheses. |
The advertiser-hosted text file must be pipe (|) delimited and should look something like the following:
Product Name 1|PRODUCT_ID_001|101 Product Name 2|PRODUCT_ID_002|102 Product Name 3|PRODUCT_ID_003|103
The itemized list must be hosted on the internet.
5. Pixel Integration
The pixel is located in the HTML of your order confirmation page that is displayed after a successful order transaction. The pixel must have the final details such as the sale amount, products or services purchased, and the program tracking information. There should only be one pixel on the confirmation page.
No Personally Identifiable Information (PII) may be passed through the pixel. PII includes but is not limited to information which can be used to distinguish or trace an individual's identity, such as their name, social security number, email address, phone number, or physical address.
The examples in this document use the Ascend standard tracking. If you are using a custom tracking domain, you can find specific code for your domain on the Tracking Integration Page in Ascend. In the examples, you will replace t.pepperjamnetwork.com with your custom domain. Instructions for implementing your custom domain can be found Custom Tracking Domain Integration Guide.
5.1. Pixel Examples
<iframe src="https://t.pepperjamnetwork.com/track?INT=DYNAMIC&PROGRAM_ID=<PROGRAM_ID>&ORDER_ID=<ORDER_ID>&ITEM_ID1=<ITEM_ID>&ITEM_PRICE1=<ITEM_PRICE>&QUANTITY1=<QUANTITY>&CATEGORY1=<CATEGORY>&COUPON=<COUPON>,<COUPON>&NEW_TO_FILE=<NEW_TO_FILE>&CLICK_ID=<CLICK_ID>,<CLICK_ID>&TYPE=<TYPE>&SEGMENT=<SEGMENT>""" width="1" height="1" frameborder="0"></iframe>
Values within the <> brackets must be assigned programmatically. A live pixel should look similar to the following:
<iframe src="https://t.pepperjamnetwork.com/track?INT=DYNAMIC
&PROGRAM_ID=000&ORDER_ID=54563131&ITEM_ID1=ABC123&ITEM_PRICE1=25000.99&QUANTITY1=1&CATEGORY1=ABC123&COUPON=COUPON1,COUPON2&NEW_TO_FILE=0&CLICK_ID=12345,23456&TYPE=1&SEGMENT=Remarketing" width="1" height="1" frameborder="0"></iframe>
If you'd like to supply multiple items, the pixel should have the following format:
<iframe src="https://t.pepperjamnetwork.com/track?INT=DYNAMIC&PROGRAM_ID=<PROGRAM_ID>&ORDER_ID=<ORDER_ID>&ITEM_ID1=<ITEM_ID>&ITEM_PRICE1=<ITEM_PRICE>&QUANTITY1=<QUANTITY>&CATEGORY1=<CATEGORY>&ITEM_ID2=<ITEM_ID>&ITEM_PRICE2=<ITEM_PRICE>&QUANTITY2=<QUANTITY>&CATEGORY2=<CATEGORY>&COUPON=<COUPON>,<COUPON>&NEW_TO_FILE=<NEW_TO_FILE>&CLICK_ID=<CLICK_ID>,<CLICK_ID>&TYPE=<TYPE>&SEGMENT=<SEGMENT>""" width="1" height="1" frameborder="0"></iframe>
Note the incrementing integer after ITEM_ID, ITEM_PRICE, QUANTITY, and CATEGORY. This is important to having a successful pixel and is further explained below
5.2. Pixel Parameters Explained
This section explains each pixel field, or parameter, you will be sending to us in detail.
Note that designates an incrementing positive integer per ordered item, even if the item is free. Please review integration examples for further explanation.
| Field Name | Description | Required | Example | Data Type / Length |
|---|---|---|---|---|
| INT | Type of integration. Your Account Manager will have this information. |
Required | DYNAMIC | String (20) |
| PROGRAM_ID | Your program ID. Your Account Manager will have this information. |
Required | 123 | Integer (10) |
| ORDER_ID | The unique order identifier that you use to reference the transaction within your system. Order items will be grouped together with this and should be unique per order. Allowed characters: alphanumeric (A-Za-z0-9), dashes (-), and underscores (_). |
Required | FT-1354342 | String (50) |
| CLICK_ID | Unique ID assigned by Ascend to each click record generated from a creative. This value is passed to the advertiser's website as the placeholder clid in the creative destination URL. This will need to be captured and stored so it can later be passed back in your pixel fire. NOTE - This parameter is not required if you are currently using the Ascend Container Tag. However, if you are not using the Ascend Container Tag, please see the additional info link below to learn more about creating your own ITP mitigation functionality. Usage: A single or comma-separated list of click IDs associated with the transaction's customer. Additional info: See Click ID Capture and Storage for more information. |
Required | 1565435,1987628 | String |
| ITEM_ID | An item ID or product SKU that is meaningful to you (usually the SKU identifier/number in your system). This is for an individual item in an order (denoted by ORDER_ID). Allowed characters: alphanumeric (A-Za-z0-9), dashes (-), underscores (_), periods (.), and colons (:). Note: Item IDs cannot be duplicated within a pixel fire. The entire quantity of a given item must be represented by a single occurrence of the item ID |
Required | SKU-423125 | String (50) |
| ITEM_PRICE | The unit price of the ITEM_ID. The price should reflect any coupon or discount that is applied to an order, and should be before shipping and taxes. This field may be set to zero (0). NOTE: The amount passed through in this field can only be a numeric value and cannot contain any characters, such as commas for amounts that are greater than one thousand dollars. If a comma exists within the amount field, it will generate an error in the system and not track properly. |
Required | 25000.99 | Float |
| QUANTITY | The quantity of ITEM_ID ordered. Must be a non-negative integer. |
Required | 2 | Integer (10) |
| CURRENCY | The currency of the item prices being passed for the order. When not supplied, amounts are assumed to be in the program's native currency. Accepted values are the three-letter abbreviations of the currencies supported by our platform: USD, CAD, GBP, EUR, AUD, CNY, JPY, INR, KRW, SGD, RUB, TRY, BRL, MXN, ARS, CHF, HKD. |
Required | CAD | String (3) |
| CATEGORY | The category ID that is meaningful to you for ITEM_ID. | Optional | ABC123 | String (64) |
| COUPON | A single or comma-separated list of promotional codes tied to a personalized coupon. This is used to ensure credit is given to the owner of the personalized creative, rather than someone who may have used it without permission. If a list is provided, the first valid code will be used. If a valid code is not provided, the sale will be attributed as normal. Note: this feature requires additional setup by your Account Manager. |
Optional | MYPROMO1 | String |
| NEW_TO_FILE | Whether or not the customer that placed the order is a new customer in your system using whatever business logic you deem appropriate. Note: This value should be 1 (one) if the customer is new or 0 (zero) if the customer is not new. |
Optional | 1 | Boolean |
| TYPE | Transaction Type (1=sale, 2=lead) If not supplied, 1 is assumed. |
Optional | 1 | Integer(1) |
| SEGMENT |
Custom Segment can be used to pass any attribute that is meaningful to you with the order.
|
Optional | Remarketing | String(64) |
| SIGNATURE |
A hashed order id (ORDER_ID) using the SHA256 hash with the private key saved by the advertiser in the pixel signing portion of the site Pixel Signature Generation Code Examples. Note: The code that generates the signature value, including the secret, should not be referenced in a way that is exposed to the user. |
Optional |
f0441870c51c73526f9d8fdb4a47593 |
String |
5.3. Real-World Integrations
HTML Integration
This is what the raw HTML should look like. In almost all cases, you will need to generate this programmatically. You can use this for reference.
<iframe src="https://t.pepperjamnetwork.com/track?INT=DYNAMIC&PROGRAM_ID=000&ORDER_ID=54563121&ITEM_ID1=P1473&ITEM_PRICE1=25000.99&QUANTITY1=3&ITEM_ID2=P1894&ITEM_PRICE2=10.95&QUANTITY2=5&CLICK_ID=113265&TYPE=1"" width="1" height="1" frameborder="0"></iframe>
PHP Integration
<?php
// Order specific data
$order_id = 'O-934234';
$order_items = array();
$order_items[] = array(
'id' => 'SKU-922320',
'quantity' => 2,
'price' => 25000.99
);
$order_items[] = array(
'id' => 'SKU-9233',
'quantity' => 1,
'price' => 189.99
);
// Pixel specific data
$integration = 'DYNAMIC';
$program_id = 123;
$new_to_file = 0; // existing customer
$transaction_type = 1;
$coupons = '';
$pixel_html = '';
$click_ids = array(1234567,2345678);
if ($order_items) {
$x = 1;
foreach ($order_items as $order_item) {
$pixel_html .=
'&' . 'ITEM_ID' . $x . '=' . $order_item['id'] .
'&' . 'ITEM_PRICE' . $x . '=' . $order_item['price'] .
'&' . 'QUANTITY' . $x . '=' . $order_item['quantity'];
$x++;
}
if ($pixel_html) {
$pixel_html =
'<iframe src="https://t.pepperjamnetwork.com/track?'; .
'INT=' . $integration .
'&PROGRAM_ID=' . $program_id .
'&ORDER_ID=' . $order_id .
'&CLICK_ID=' . implode($click_ids, ',') .
'&COUPON=' . $coupons .
'&NEW_TO_FILE=' . $new_to_file .
'&TYPE=' . $transaction_type .
$pixel_html .
'" width="1" height="1" frameborder="0"></iframe>';
echo $pixel_html;
}
}
?>
jQuery JavaScript Integration
<script>
// Assuming order_items and order_id data would be pulled from the confirmation
// page itself or by AJAX. Populated here for this example.
var order_items = [
{ 'id': 'SKU-38942', 'price': '25000.99', 'quantity': 2 },
{ 'id': 'SKU-934', 'price': '394.22', 'quantity': 1 }
];
var order_id = 'O-04032-052015';
var transaction_type = 1;
var new_to_file = 0;
var coupons = '';
function pepperjam_pixel (order_id, order_items, new_to_file, transaction_type) {
var pixel_html = '';
var integration = 'DYNAMIC';
var program_id = 123;
var click_ids = [1234567,2345678];
if (order_id && order_items) {
jQuery.each( order_items, function (i, order_item) {
pixel_html += '&' + 'ITEM_ID' + i + '=' + order_item.id +
'&' + 'ITEM_PRICE' + i + '=' + order_item.price +
'&' + 'QUANTITY' + i + '=' + order_item.quantity;
});
if (pixel_html) {
pixel_html = '<iframe src="https://t.pepperjamnetwork.com/track?'; +
'INT=' + integration +
'&' + 'PROGRAM_ID' + '=' + program_id +
'&' + 'ORDER_ID' + '=' + order_id +
'&' + 'CLICK_ID' + '=' + click_ids.join() +
'&' + 'COUPON' + '=' + coupons +
'&' + 'NEW_TO_FILE' + '=' + new_to_file +
'&' + 'TYPE' + '=' + transaction_type +
pixel_html +
'" width="1" height="1" frameborder="0"></iframe>';
}
}
$('body').append(pixel_html);
}
pepperjam_pixel(order_id, order_items, new_to_file, transaction_type);
</script>
5.4. Additional Functionality
A single or comma separated list of coupon codes tied to a personalized coupon. It is used to ensure credit is given to the owner of the personalized creative, rather than someone who may have used it without permission. If a list is provided, the first valid code will be used. If a valid code is not provided, the sale will be attributed as normal. This is an optional parameter and the feature requires additional setup by your Account Manager.
You may specify whether or not the customer that placed the order is a new customer in your system using whatever business logic you deem appropriate. This value should be 1 (one) if the customer is new or 0 (zero) if the customer is not new. This is for rules(s) that depend on if the customer is a new customer or not.
<iframe src="https://t.pepperjamnetwork.com/track?PROGRAM_ID=<PROGRAMID>&INT=DYNAMIC &ITEM_ID1=<ITEM_ID>&ITEM_ID2=<ITEM_ID> &QUANTITY1=<QUANTITY>&QUANTITY2=<QUANTITY> &ITEM_PRICE1=<ITEM_PRICE>&ITEM_PRICE2=<ITEM_PRICE> &ORDER_ID=<ORDER_ID>&COUPON=<COUPON>,<COUPON>&NEW_TO_FILE=<NEW_TO_FILE>&CLICK_ID=<CLICK_ID>,<CLICK_ID>&TYPE=<TYPE>&SEGMENT=<SEGMENT>" width="1" height="1" frameborder="0"></iframe>
5.5. Testing Your Pixel Integration
Before making any changes to test for successful pixel integration, it is important to create a backup of any page or pages that will be modified. It is important to test the pixel on your confirmation page to make sure that everything is working properly. Pixel code should be placed on the Confirmation or Thank You Page.
Partnerize will review your submitted HTML code and also place a test sale to make sure that the integration was performed successfully. Periodically, the Partnerize staff may place tests sales to make sure that the pixels are still working correctly.
5.6. Pixel Integration Problems
A properly integrated pixel is extremely important to a successful marketing campaign. Be sure that you completely understand how to implement pixel tracking. Problems such as incorrect reports can be caused from incorrect values being entered into the tracking pixel at the time of sale. At least one successful test must be completed. The correct information must be set in the pixel so that the tracking and reporting systems function properly.
6. Common Phrases and Definitions:
| Field Name | Description |
|---|---|
| Advertiser | A company or person that sells goods or services online. Advertisers work with publishers to direct traffic to their goods and services. |
| Affiliate | See Publisher. |
| Banner Ad | An electronic image used to advertise an advertiser's products or services. |
| Click ID |
Unique ID assigned by Partnerize to each click record generated from a creative. This value is passed to the advertiser's website as the placeholder clid in the creative destination URL. This will need to be captured and stored so it can later be passed back in your pixel fire. Usage: A single or comma-separated list of click IDs associated with the transaction's customer. Additional info: See Dynamic Tracking - Click ID Capture and Storage for more information. |
| Click-Through | When a visitor clicks an ad that is linked to an advertiser's website. |
| Confirmation Page | The page displayed after a purchase is completed or a form is submitted. |
| Cookie | Information stored on a visitor's computer for remembering preferences or storing tracking information so that advertisers know which publisher directed a visitor to their site |
| Cookie Duration | A set period of time that a cookie will be stored on a visitors computer for purposes of tracking return visits. |
| Deep Linking | Linking directly to a page other than the homepage. |
| Domain | A computer or group of computers on a network that are administered under the same protocol. For example: www.pepperjam.com. |
| Gateway Advertiser | The type of advertiser that does not log all transactions through Ascend and instead uses a URL with special triggers (name & value pairs) that enable the Ascend tracking tool to log the transactions. |
| Home Page | A website's main page. |
| Incentivized Traffic | Visitors that receive compensation (incentives) for visiting a site. |
| Landing Page | The page that visitors are directed to after clicking a link. Usually a websites homepage. |
| Merchant | See Advertiser. |
| Publisher | An independent promoter of advertiser products and services. |
| Standard Advertiser | The type of advertiser that logs all website transactions through Ascend. Tracking these transactions can be done from anywhere in the website and does not require a specific "landing page". |
| Super Affiliate | A publisher that performs extremely well and generates a large percentage of an advertiser's activity. |
| Text Ad | A text-based link used to advertise an advertiser's products or services |
| Tracking Pixel | An iframe or image (1x1 pixel) used to place tracking information on a visitors computer, usually placed on the sale confirmation page. |
| URL | Uniform resource locator; an address or location on the internet. |