If you have any question left, please drop a note with the discussion link of this page.

Changeover 2009 to 2011

From Wiki.zanox.com

Jump to: navigation, search

On November 3, 2012, according to our migration strategy, we will be shutting of the 2009-07-01 version of the Publisher API.

The purpose of this page is to hopefully provide you with everything you need to switch versions with as little disruption as possible. If you have any questions, please share them with the community at the developer@zanox.com mailing list, to ensure the migration is as smooth as possible for everybody. If you are not yet on the mailing list, instructions for registering are on the Web Services home page.

Contents

Overview

In a case like the following, all you need to do is change the version in the URL, from:

http://api.zanox.com/xml/2009-07-01/programs/program/123?connectid=580599047DF8F5311043

to:

http://api.zanox.com/xml/2011-03-01/programs/program/123?connectid=580599047DF8F5311043

If you are using one of our client libraries to access the Publisher API, in most cases you will only need to swap the folder containing the library, and change the line in your code referring to the version. This is outlined below..

In some cases, however – e.g. applying to programs and searching products – the methods themselves have changed, and you will need to update your code accordingly.

Changeover Checklist

Several methods exist in the 2009 version but not in the 2011. If the following methods are in your code, you will need to migrate the functionality to the new methods:

Some methods have had their signatures changed:

  • CreateProgramApplicationRequest –2011 version added field "publisherComment"
  • GetAdmediaRequest - 2011 version added field "q", removed field "ip"
  • GetAdmediumRequest - 2011 version added field "trackingLink"
  • GetProductCategoriesRequest - 2011 version added field "region"
  • GetReportBasicRequest - 2011 version removed fields "admediumFormatId", "dateType"

Several data types have changed in the 2011 version. This may break code which generates classes using the WSDL:

  • admediumItem – 2011 version added fields “description”, “group”, “instruction”, “tags”
  • adspaceItem – 2011 version added field “checkNumber”; 2009 “lang” -> 2011 “language”; 2011 removed field “keywords”
  • productItem – 2011 version added fields “merchantCategory”, “merchantProductId”, “priceOld”, “shipping”, “shippingCosts”
  • profileItem – 2011 version added fields "currency","isAdvertiser","isSublogin","language","loginName","userName"
  • programItem – 2011 version added fields “policies”, “returnTimeLeads”, “returnTimeSales”, “status” , “terms”, “termsUrl”; 2011 removed field “conditions” (replaced in 2011 by method GetTrackingCategories)
  • reportItem – the 2011 version introduced the concept of statsType, which essentially takes the 2009 reportItem structure and breaks it down into separate entities for “total”, “open”, “approved”, “confirmed”, and “rejected”; in addition, the 2011 version added the fields “application” and “mediaslot”, while removing the fields "clickCity", "clickCommission", "clickCount", "clickCountry", "clickRegion", "dayOfWeek", "hourOfDay", "leadCommission", "leadCount", "reviewState", "saleAmount", "saleCommission", "saleCount"
  • saleItem / leadItem – the 2011 version added fields “category”, “clickInId”, “reviewNote”, “trackingCategory” while removing the fields “category”, “lptId”
  • programApplicationItem – the 2011 version added fields “createDate”, “allowTpv”, “approvedDate”, “publisherComment”, “advertiserComment”


 Client Library Users

If you use one of the zanox client libraries, especially one of the less strongly typed ones like PHP, switching should be fairly painless.

Upgrading PHP Client Library

If you are currently using the 2009 version of the PHP Client Library:

  1. Assuming the 2009 library is in the directory \client, delete the contents of this directory.
  2. Download the newest version of the PHP Client Library .
  3. Unzip the 2011 library to \client so that the file ApiClient.php is in \client\ApiClient.php
  4. In the 2009 library, the client's factory method required the version number, e.g. ApiClient::factory(PROTOCOL_SOAP, VERSION_2009_07_01). The method can now be called with no version as in the version below.
 
<?php
require_once 'client/ApiClient.php';
 
$client = ApiClient::factory(PROTOCOL_SOAP);
$client->setConnectId('_YOUR_CONNECT_ID_');
$client->setSecretKey('_YOUR_SECRET_KEY_');
 
$sales = $client->getSales('2011-01-24', 'trackingDate', NULL, NULL, NULL, 0, 50);
var_dump($sales);
?>
 


Upgrading .NET Client Library

If you are currently using the 2009 version of the .NET Client Library:

  1. Assuming you have a project with a reference to the 2009 zanoxClientLib, remove the reference to this library.
  2. Download the newest version of the [| NET Client Library] from codeplex.com.
  3. Add a new reference to the 2011 library.
  4. In your project, your namespaces to the 2009-07-01 PublisherAPI need to be changed to 2011-03-01, the namespace of Connect needs to be changes to the 2011-05-01 version nunmber.
 
var publisherAPI = new PublisherAPI(); 
var permanentDeveloperCredentials = new sessionType(){
        connectId = Properties.Settings.Default.ConnectId,
        sessionKey = Properties.Settings.Default.PublicKey,
        secretKey = Properties.Settings.Default.SecretKey
}; 
 
var profile = publisherAPI.GetProfile(zanoxConnectSession);
var sales = publisherAPI.GetSales(zanoxConnectSession, ...some more filters);
var incentives = publisherAPI.GetIncentives(zanoxConnectSession, ...filters);
 

Tracking Categories

One important change that has come up quite a bit as we approach the shutoff date is that program commissions have been moved from the ProgramItem to their own resource: TrackingCategoryItem. The solution in the 2009 API returned only the program's default commissions. TrackingCategoryItem returns the defaults (in slightly different form - see below), as well as commission models assigned by the program to specific ad spaces.

Some important points:

  • The request must be made with an ad space ID and a program ID. If the ad space is not applied for the program, the default commission will be returned.
  • Previously, commission ranges were returned (e.g. "minpercent", "maxpercent"). Because the range of relevant tracking categories is now returned, this is no longer the case (see PHP example below for the fields that are returned).
  • For now, this resource is only available via SOAP
  • ProgramItem was available via an unsecure call, i.e. only a Connect ID was required. However, since the TrackingCategoryItem can contain publisher-specific data, it is retrieved with a secure call. As such, we strongly recommend using the Client Library to retrieve this.

Retrieving tracking categories with the PHP Client Library

  1. Be sure you have the most recent version of the PHP Client Library from GitHub (https://github.com/zanox/api_client_php/zipball/master). This method was only added to the Library on March 14, 2012.
  2. Call the tracking categories as follows:
 
<?php
require_once 'client/ApiClient.php';
 
$client = ApiClient::factory(PROTOCOL_SOAP);
$client->setConnectId('_YOUR_CONNECT_ID_');
$client->setSecretKey('_YOUR_SECRET_KEY_');
 
$adspaces = $client ->getAdspaces();
 
$adspaceId = $adspaces->adspaceItems->adspaceItem[0]->id; // enter one of your adspaces. if this ad space is not applied for the program, the default commission will be returned
$programId =;
 
$categories = $client->getTrackingCategories($adspaceId, $programId);
 
foreach($categories->trackingCategoryItem->trackingCategoryItem as $category){
  echo "View fixed: " . $category->viewFixed . "<br>";
  echo "Click fixed: " . $category->clickFixed . "<br>";
  echo "Lead fixed: " . $category->leadFixed . "<br>";
  echo "Sale fixed: " . $category->saleFixed . "<br>";
  echo "Sale percent: " . $category->salePercent . "<br><br>";
}
 
?>
 

The result will have the following format:

 
            <page>0</page>
            <items>128</items>
            <total>128</total>
            <trackingCategoryItem>
                <trackingCategoryItem id="0">
                    <name>default</name>
                    <program id="…">PROGRAM_NAME</program>
                    <adspace id="…">ADSPACE_NAME</adspace>
                    <transactionType>sales</transactionType>
                    <description>default</description>
                    <saleFixed>4.5</saleFixed>
                    <salePercent>0.0</salePercent>
                </trackingCategoryItem>
 
Personal tools