Archive for December, 2007

How to move from Google Checkout’s HTML API to the XML API (in PHP)

We recently moved a client’s Google Checkout solution from the HTML API to the XML API. It seemed tough when we were doing it but if we had to do it again now it would be a breeze. So the goal of this article is to save you the hassle of learning the steps of how to move from the HTML API to the XML API.

What you’ll need:

  • A Google Merchant account
  • A Google Sandbox account (can be part of the Merchant account)

Procedure:

Step 1 – Get the Google Libraries and Example carts

First stop, take a quick look the Google Developer page for Checkout users – this is your portal into Google as a Google Checkout developer.

Now take a look at the XML API page. We built our cart using PHP, so we used the PHP examples. Examples in other languages can be found here. Again, it’s worth taking a minute to familiarize yourself with this page.

And now for the good news – Google Sample Code for creating an XML API cart. We went to the PHP category and clicked on the download link to get the sample code. This little bundle contains pretty much everything you need to build a Google XML API cart quickly and easily.

Step 2 – Open the sample code and take a look inside

Inside the folder you just downloaded you’ll see a lot of stuff. There are only two folders that you need concern yourself with however.

  • Library – Our favourite because it contains all of the code you’ll need to create you XML documents and yet you will probably never have to touch a single line of the code in here. It’s all ready for you – these are libraries, code that is prepared for you, if you like.
  • Demo – Almost as good! All you have to do is look at the examples in here, tweak them so they use your own data instead and test it in your Google Sandbox.

Step 3 – Setting it up

Now you’ve got your code Libraries and Demo files, you’re ready to upload them, modify them and test them in your Sandbox. Here’s how:

  • Upload the sample code to your server. We created a folder called Google_Checkout and dropped the “demo”, “library” and “unitTest” folders in there.
  • Navigate to Demo>cartdemo.php and make a backup before we start hacking at it
  • Open cartdemo.php from on your server and scroll down to where you see this:
     // Invoke any of the provided use cases
    // UseCase1();
    // UseCase2();
    // UseCase3();
    Usecase();
    DigitalUsecase();
    CarrierCalcUsecase();

    The Google coders have thoughtfully provided you with various different types of cart to play with all in this single file. We’re only going to use one of them, so comment the code so it looks like this. You can experiment with the other options later once you’ve understood the basics.:

     // Invoke any of the provided use cases
    // UseCase1();
    // UseCase2();
    // UseCase3();
    Usecase();
    // DigitalUsecase();
    // CarrierCalcUsecase();

    Great! Step one is complete and your cart will only use one calculation method: the one called Usecase();

  • Now we need to go and get our Sandbox merchant ID and Key. Where? Login to your Google Checkout merchant’s account click on “My Account” then “Checkout Sandbox” then go to your “Settings” tab. Your Sandbox ID and Key should be on the right or under the integration link (bottom left)
  • Return to cartdemo.php and a few lines down from where we left off you’ll see:
    
          $merchant_id = "";  // Your Merchant ID
    $merchant_key = ""; // Your Merchant Key
    $server_type = "sandbox";
    $currency = "USD";

    Just fill in your sandbox info for Merchant ID and Key and we’re good to go!

  • Now we’ll check the Sandbox is working. Load the cartdemo.php page into your browser via the server (http://anExample.com/Google_Checkout/Demo/cartdemo.php

    You should see a Google Button. Click on it and you’ll be taken to the Sandbox checkout and in the background… your site created the requisite XML!!!

Step 4 – Integrate your basket

Now the Sandbox is working in XML mode all you have to do is modify the predefined cart items that Google provides with your own. Here’s how:

  • Navigate to the lines of code just a little further down in the cartdemo.php page. You should see this:
    $item_1 = new GoogleItem("item name", // Item name
    "item desc", // Item description
    $total_count, // Quantity
    10); // Unit price
    $cart->AddItem($item_1);

    And happily, from here on in it’s really simple. Just create a loop for however many different items there are in your basket and build your basket. Here’s a possible example:

    
    foreach ($_SESSION['theCart'] as $line){ //The 'theCart' session is a basket array.
    $num_items = $line['Qty']; //Basic info about each item
    $item_price = ($line['unit_price']);
    $item_name = strtoupper(($line['unit_name']));
    $item_category = ($line['unit_category']); //Something like the Google Description
    // Create cart item
    //The curly braces allow the appending of
    //a numeric suffix to a varible you are creating
    ${"item_".$x} = new GoogleItem($item_name, // Item name
    $item_category, // Item description
    //If you use Carrier Calculated shipping you must provide weight
    $the_weight = (($line['unit_weight'])/16);
    $num_items, // Quantity
    $item_price, // Unit price
    'LB',
    $the_weight //Item Weight
    );

    // Add items to the cart
    $cart->AddItem(${"item_".$x});

    $x++; //Increase count

    } //end foreach line item

    } else {

    echo "No Valid Basket - Sorry!!!!!";
    }

Step 5 – Getting ready to go live

OK, you’ve done the above but your wondering how to put all of this into your checkout page. Take a look! Just put this line of code where your existing HTML API Google Checkout button is:

<?php include '/Google_Checkout/Demo/cartdemo.php'; ?>

We’re kidding, right? Nope! You can now throw away all those input hidden statements you were using previously and put this single line. THe XML is all generated by that single include.

If you want to see the XML being created for debugging, go to the bottom of your usecase() function (not necessarily the bottom of the document) and uncomment this:

// Display XML data
// echo "<pre>";
// echo htmlentities($cart->GetXML());
// echo "</pre>";

Step 6 – Set Shipping and Tax options

One of the big advantages of using the XML API is that it allows you a lot more control over shipping and taxes. There are a multitude of possibilities here and to get the most out of them you should take a look at the Google XML API guide. There are further documents linked to that deal with Carrier Calculated shipping, Taxes, etc.

If you’re using our Usecase() example basket, you’ll see some shipping and tax options have already been set:

  // Add shipping options
  if($total_count < 3){
		 $ship_1 = new GoogleFlatRateShipping("USPS Priority Mail", 4.55);
  }else{
		 $ship_1 = new GoogleFlatRateShipping("USPS Priority Mail", 6.2);
  }
  $Gfilter = new GoogleShippingFilters();
  $Gfilter->SetAllowedCountryArea('CONTINENTAL_48');
  
  $ship_1->AddShippingRestrictions($Gfilter);
  
  $cart->AddShipping($ship_1);
  
  // Add tax rules
  $tax_rule = new GoogleDefaultTaxRule(0.05);
  $tax_rule->SetStateAreas(array("MA"));
  $cart->AddDefaultTaxRules($tax_rule);
  
  // Specify 
  $cart->SetEditCartUrl("https://www.example.com/cart/");
  
  // Specify "Return to xyz" link
  $cart->SetContinueShoppingUrl("https://www.example.com/goods/");
  
  // Request buyer's phone number
  $cart->SetRequestBuyerPhone(true);
  
  // Display Google Checkout button
  echo $cart->CheckoutButtonCode("SMALL");

This should all be fairly self explanatory. There are loads more examples throughout the demo file so scroll on down and take a look.

Step 7 – Put it live

If everything is happening as expected you can then put your basket live.

  • Return to your Google Merchant’s Account, leave the Sandbox area and go to your actual account information. Get your ID and Key and use them instead of the Sandbox values (see step 3 point 5 above). You’ll also need to change the line $server_type = “sandbox”; to $server_type = “checkout”;
  • That’s it – you’re live!

Disclaimer

Metaclarity does everything it can to ensure the information we post is accurate. However, Metaclarity can accept no responsibilty for any damage or loss of data use of the above information might cause.

Use rsync to backup your Mac to a remote server via SSH

If you find online backup solutions expensive and heavy on your system, you might be pleased to hear there is a cheap, easy way to create a mirror backup your Mac (or other UNIX variant) to a secure online server. And as of Mac OS X Leopard, rsync will even transfer metadata associated with your files like Tags and Comments.

This method does not allow you to roll back to previous dated backups like certain backup solutions do (Time Machine, for example). What it does is create a mirrored backup of your Mac on a remote server, so it’s best used in conjunction with a local hard-drive based incremental backup solution.

Still, if the house burns down your files will be safe and once you’ve done the initial backup, rsync is very efficient at keeping your remote backup mirrored with your disk.

In this example we’re going to backup the currently logged-in user’s Documents folder.

What you’ll need:

-rsync running on you Mac (it’s there on 10.4 and 10.5)
-An Internet Service Provider (ISP) who allow you to connect via SSH. [examples 1 2 3]

Procedure:

Step 1 – Set up the remote server

  • You’re going to need shell access to your server. If you don’t already have it and you use cPanel to administer your server then there is often a “Request Shell Access/Remote Login” option. If there isn’t, contact your ISP directly.
  • With shell access set up, create a folder that is outside of the scope of your webserver. You could use FTP to do this, if you prefer. For example, set up a folder called private_BKP at the root level of your server and put a folder in there called Mac_One_BKP. The path is then /home/private_BKP/Mac_One_BKP and its in there that we’re going to put the contents of our Documents folder.

Step 2 – Set up your Mac

  • Launch the Terminal application (found in your Utilities folder).
  • Type rsync -avz -e ssh /Users/yourUserName/Documents yourLoginName@yourServer.com:'/home/private_BKP/Mac_One_BKP'
    An easy way to do the first part is to type rsync -avz -e ssh then drag and drop your Documents folder right into the Terminal window. Watch out that your system does not add a slash ‘/’ after the word ‘Documents’. If it does, just remove it. Why? The slash will mean rysnc will copy the contents of the Documents folder rather than copying the whole folder.
  • For the second part, you need to guarantee that ‘yourLoginName@yourServer.com:’/home/private_BKP/Mac_One_BKP’ is pointing to the folder you created on your remote server.
  • Before starting the transfer, you may want to exclude certain files and folders from being sent to the server (very private stuff, caches, etc.) To do this, see Step 3 – Deletes and Excludes below.
  • Press Return and you’ll be asked for your password. Provide it and you should see a long list of files scrolling in the Terminal window. These are the files moving from your machine to the remote server.

Note 1: If you want to checkout what the -avz -e stuff does, take a look at the rsync man page
Note 2: Your first backup can take hours, if not days (don’t worry – it’ll be MUCH faster the second time round thanks to rsync’s ability to transfer only the parts of files that have changed. Take a break from the computer and have a buy a real copy of this instead) this instead

Step 3 – Deletes and Excludes

One you’ve backed-up your Mac’s Documents folder using the method above there will come a time when you will want to run the script again – like when you add new content to your folder! However, you many also have deleted some content from your Documents.

  • To have rsync delete files on the remote server that are no longer on your machine, add --delete
    ex: rsync -avz --delete -e ssh /Users/yourUserName/Documents [etc.]
  • To have rsync exclude the transfer of certain files to the remote server , add --exclude='myFileName'
    ex: rsync -avz --delete --exclude='myFileName' -e ssh /Users/yourUserName/Documents [etc.]
    You can add multiple –exclude statements or add a list via an –exclude_from file (see the manual)

Disclaimer

Metaclarity does everything it can to ensure the information we post is accurate. However, Metaclarity can accept no responsibilty for any damage or loss of data use of the above information might cause.