What is Agua Biz?

Agua Biz Account Structure

Agua Biz is a mashup of the Agua Ajax application and Google Checkout. It allows users to manage their Google AdWords accounts in an interactive and asynchronous way, and at the same time seamless integration of Google Checkout functionality. This makes it an interesting tool for online vendors, and can be seen as a simple AdWords-Checkout integration demo. The application behaves almost like a program on your desktop, but runs entirely in your web browser.

In order to access the AdWords API, Agua Biz uses the APIlity library. Agua Biz is meant to be an example of what you can do with this library. Feel free to learn from the code, adapt it to your needs, or simply inspire yourself by giving it a try.

The name Agua Biz stands for APIlity GUI for AdWords Business.

Agua Biz Stocks Agua Biz Buyer Click on the screenshots to see the full image.
 
Left image: Agua Biz stocks section with automatic creative feature.
Right image: Agua Biz buyer section with Checkout integration.

The Agua Principle

Agua Principle
  1. The application runs on a web server (which for example can be an Apache on localhost) and generates XmlHttpRequests in order to access locally stored so-called intermediate PHP files.
  2. These intermediate PHP files act as an interface between Agua running in the web browser, and the Google APIlity library. As APIlity supports XML and native PHP types as data exchange formats, the intermediate PHP files need to translate between these two formats.
  3. Having received the instruction embedded in the XmlHttpRequest, APIlity then interacts with the Google AdWords API and processes the desired tasks.
  4. Afterwards, the response is forwarded to the waiting XmlHttpRequest and finally arrives at the Agua application.

This principle allows mutliple requests to be sent in parallel. In practice this means that for example when you are waiting for all AdGroups to download, you can edit the data of another Campaign in between, i.e. the requests are non-blocking.

Requirements

Being an Ajax application, Agua Biz requires a current web browser with JavaScript enabled. Additionally, your web server must have PHP4 or PHP5 and MySQL (no matter what version) installed. In order to make the installation process as smooth as possible, it is recommanded to have phpMyAdmin installed, too. In general, if your web server fulfills the APIlity requirements, together with a somewhat current web browser, you should be able to run it without problems.

Installation

All you have to do is download the most current version and put it in a folder on your web server. Agua ships with a correctly pre-configured APIlity version, i.e. you do not need to know the internals of this library. Second, you need to setup a simple database that simulates a very basic web store. This can be done using the INSTALL.SQL script. In phpMyAdmin, select a database (the standard database "test" is a good choice) where you want to install the two tables. Then execute the SQL install script using phpMyAdmin's SQL tool. If everything went well, you now should have two tables ("t-shirts", and "creatives-items") in some testing database.

Getting started

In order to use the application, you need both

The process of creating these accounts is guided by a wizard and should be no big deal. Please consult the particular help section if you should run into trouble.

To successfully login, in the Login Section first enter the desired login data in the file settings.ini. This file consists of three sections:

Once you have correctly installed the application, say in the folder htdocs/agua_biz/ assuming you are using Apache, try accessing the files index_buyer.php and index_vendor.php. Therefore type http://localhost/agua_biz/{index_vendor|index_buyer}.php in your web browser's address bar. If everything went well, you should now either see the Login Section of the application, or the web shop web front-end. Please refer to the above screenshots to verify your results.

  1. If you have entered all the required information into the settings file correctly, you should see your login data in the Login Section.
  2. Click the "Login And List My Clients" button.
  3. Second, choose one of your clients in the client selection box in the Client Select Section and click the "Login To This Account" button.
  4. Third, in the Account Structure Section all Campaigns of the selected client will be displayed. Dependent on the size of the client's account, this may take some time.

Ajax Activity

Agua is an Ajax application. This means that requests can be sent in an asynchronous way. To signalize activity, Agua opens a color-changing box in the upper right corner of the application, saying "Loading" plus the operation being performed. See the example below:
Loading getAllCampaigns...

Meaning of the icons

Downloads the corresponding AdWords item (costs quota).
Reloads the corresponding AdWords item (costs quota).
The corresponding tree branch and all sub-branches of the account structure are shown (does not cost quota)
The corresponding tree branch and all sub-branches of the account structure are hidden (does not cost quota)
Updates an AdWords item if changes have been made. Outstanding changes are highlighted with a red background. Once the changes have been confirmed, the corresponding fields are highlighted with a green background for a short period of time (costs quota).
Deletes the corresponding AdWords item (costs quota) after confirming the deletion.
Creates a new Campaign (costs quota).
Creates a new AdGroup (costs quota).
Creates a new Creative (costs quota).
Creates a new Criterion (costs quota).