What is Agua?

Agua Account Structure

Agua is an Ajax application which allows users to manage their Google AdWords accounts in an interactive and asynchronous way. 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 uses the APIlity library. Agua 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 stands for APIlity GUI for AdWords.

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 requires a current web browser with JavaScript enabled. Additionally, your web server must have PHP4 or PHP5 running. 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, put it in a folder on your web server and that's it. Agua ships with a correctly pre-configured APIlity version, i.e. you do not need to know the internals of this library.

Getting started

Once you have correctly installed the application, say in the folder htdocs/agua/ assuming you are using Apache, try accessing the file index.php. Therefore type http://localhost/agua/ in your web browser's address bar. If everything went well, you should now see the Login Section of the application.

  1. To successfully login, in the Login Section first enter
    • The email address of the "My Client Center" manager in your Google AdWords account
    • The password of this "My Client Center" manager
    • The developer token which can be found in the API section of your AdWords account
    • The application token which can also be found in the API section of your AdWords account

    Alternatively, you can enter the same data in the file settings.ini in order to save you some work when you use the application regularly.
     
    Then click the "Login And List My Clients" button.
  2. Second, choose one of your clients in the client selection box in the Client Select Section and click the "Login To This Account" button.
  3. 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).