AdWords Rails Demo
AdWords API with Ruby on Rails demo code walkthrough
This article describes the main aspects of the AdWords on Rails sample application. It covers the demo functionality only and this is not intended to be a Rails development guide.
We expect you to have already downloaded and set up the demo application as covered in the README file. The actual application files are located under the
The first thing the demo tries to acquire is user authorization information. While the application itself has no stored data, it will not be functional without access to the AdWords API. This is achieved via ApplicationController before_filter.
The demo application uses OAuth2 authentication method which requires an access token to access the API. In case the token is present in the current session, we allow the view to render, otherwise the browser is redirected to the Google login page.
Note: Here we only check if we have any token in the session. We can’t check if it is valid as the only way to find this out with the current library is to make an AdWords API request.
The login process is handled by LoginController and consists of two parts on our side:
- Make a library authorize request. If the application was already granted an access by the user a valid token will be returned. Otherwise, an exception is thrown with a URL for authorization in parameters. We use the URL in the view to invite the user to log in and authorize the application.
Note: Based on library configuration, the request may succeed right away. To configure this behavior you need to provide the secret parts of the token in the library configuration file.
- Once the Google authorization is complete, the browser will be redirected to the URL provided in the authorization request. This will be handled by the callback method of the LoginController.
Here we store the token received in the session so the subsequent requests to the application could re-use the auth information.
We also have the logout method in the controller. Here we clear up the current session and redirect to the Google log out page.
Note: It is important to not only clear session information but also redirect user to the Google logout page. Otherwise, the user will still be logged in for other services.
Obtaining AdwordsApi object
In order to be able to access the AdWords API object from any controller we created a get_adwords_api method in the ApplicationController. The method creates a new instance when required but re-uses an existing one if present.
When creating a new AdwordsApi object we do the following:
- Identify the location of the configuration file relative to the Rails location
- Create a new instance with the configuration file
- Update the API credentials from the current session, when available.
In order to access the AdWords API it is required to set the following parameters:
:oauth2_token(obtained during authorization)
:client_customer_id(the customer ID to run requests against)
Selecting AdWords account
For most of the AdWords API queries an advertiser account needs to be specified. An exception to this is the ManagedCustomerService which we use to retrieve the account hierarchy. Once retrieved, we render the tree for the user to select an account to work with.
This part is handled by AccountController. It retrieves the data via the API and passes it to the Account model to create Account objects. As the
AdwordsAPI object is session-specific we don't want to offload this completely to the model.
The Account view displays the accounts hierarchy and allows the user to choose one of them. Account selection part is as simple as setting session variable from HTTP parameters. We do not do any validation here as providing an invalid ID will result in authorization error on the AdWords side anyway.
Running a simple query
To demonstrate a simple API query we'll run a get request to the CampaignService. The result will be the list of the selected account campaigns formatted in a simple table.
For campaigns handling we use the CampaignController. As the number of campaigns can be large we limit the query to the first 50 results. Otherwise the process is the same: the data is retrieved and passed to the Campaign model to be wrapped as objects.
In case an error occurred, we log the details to the standard logger. In most cases you do not want the end user to know too many technical details.
Retrieving a report
Reports handling is implemented in the ReportController. It uses two models to identify report and report format which are used in the view rendering. Here we allow user to provide a list of fields requested in a free form field. This is simpler for the demo but in a production application you may want to limit the choice to the fields actually available.
When the data is downloaded, we offer user to download it via the Rails send_file helper. Some additional efforts are made to make sure the default filename matches the report format selected.
For error handling we chose to provide the full error message to the user here. In most cases the error will be due to incorrect fields provided by the user in parameters and we want to pass this information so the request options could be fixed.