Readme.txt in adwords4r-13.0.1 vs Readme.txt in adwords4r-15.0.1

- old
+ new

@@ -1,48 +1,60 @@ -Google adwwords4r Library +Google adwords4r Library ------------------------- -Welcome to adwords4r: Bringing the delights of ruby programming to the AdWords world! +Welcome to adwords4r: Bringing the delights of Ruby programming to the AdWords +world! Documentation and comments are a work in progress. Useful Web Resources -------------------- -- AdWords home: https://adwords.google.com/ -- AdWords API discussion forum: http://groups.google.com/group/adwords-api -- AdWords API documentation: http://www.google.com/apis/adwords/developer/index.html -- This project's Google Code page: http://code.google.com/p/google-api-adwords-ruby/ +- AdWords home: + https://adwords.google.com/ +- AdWords API discussion forum: + http://groups.google.com/group/adwords-api +- AdWords API documentation: + http://code.google.com/apis/adwords/docs/developer/index.html +- This project's Google Code page: + http://code.google.com/p/google-api-adwords-ruby/ Docs for Users -------------- +1 - Instalation: + adwords4r is a ruby gem. See http://docs.rubygems.org/read/book/1 Install it using the gem install command. -> gem install --remote adwords4r +> gem install --local adwords4r The following gem libraries are required: -- soap4r v1.5.8 or greater +- soap4r v1.5.8 - httpclient v2.1.2 or greater + +2 - Using the client library: + It's pretty easy to use. -See http://docs.rubygems.org/read/chapter/3#page70 for how to set the rubygem environment. +See http://docs.rubygems.org/read/chapter/3#page70 for how to set the rubygem +environment. export RUBYOPT=rubygems or ruby -rubygems my_program_that_uses_gems If you do not use the rubygems option, you need to add require 'rubygems' at the beginning of your programs. -Then +Then: require 'adwords4r' adwords = AdWords::API.new -creates a driver for the latest version of AdWords API using a credentials file in ENV['HOME']/adwords.properties +creates a driver for the latest version of AdWords API using a credentials file +in ENV['HOME']/adwords.properties There is an example credentials in the root adwords4r directory. You can also pass API a manually constructed AdWordsCredentials object like: adwords = AdWords::API.new(AdWords::AdWordsCredentials.new({ 'developerToken' => 'DEVELOPER_TOKEN', 'applicationToken' => 'APPLICATION_TOKEN', @@ -50,41 +62,83 @@ 'password' => 'PASSWORD', 'email' => 'user@domain.com' 'clientEmail' => 'user2@domain.com', })) -If you want something more specific, use the optional parameters of the constructor -adwords = AdWords::API.new(credentials, version) +Then, just specify which service you're looking to use, and which version: +account_srv = adwords.get_service(13, 'Account') -In order to use the sandbox, you can add a credential named -alternateUrl like: -alternateUrl=https://sandbox.google.com/api/adwords/v12/ +and you should now be able to just use the API methods in the object you were +returned: +client_accounts = account_srv.getClientAccounts -Then just use methods of the API against your driver. -See sample code in the examples directory for working examples you can build from. +See the code in the examples directory for working examples you can build from. + +2.1 - Using the Sandbox: + +In order to use the v13 sandbox, you can add a credential named alternateUrl: +alternateUrl=https://sandbox.google.com/api/adwords/v13/ + +As for v200902, the alternateUrl parameter is currently ignored, since only the +sandbox is available at the moment. For this API version, all requests will be +sent to the sandbox, using the "email" and "password" fields defined in the +credentials for authentication, and clientEmail for specifying which client +account to access. Developer and application tokens are ignored. + +This way, it's possible to access both the v13 and v200902 sandboxes +simultaneously. Since they share a common backend storage, it is possible for +your application to choose between v13 and v200902 services at will, mixing and +matching them. + +The multiple_versions.rb code sample shows you how to build an application using +v13 and v200902 services simultaneously. + + +2.2 - Logging: + It is often useful to see a trace of the raw SOAP XML being sent and received. -To enable this, set the ADWORDS4R_DEBUG environment variable to TRUE. -e.g. in the bash shell, export ADWORDS4R_DEBUG=TRUE -or from your Ruby code, ENV['ADWORDS4R_DEBUG'] = 'TRUE' -The SOAP logs will be written to the current directory. +The quickest way of achieving this when debugging your application is by setting +the ADWORDS4R_DEBUG environment variable to TRUE; e.g. in the bash shell: +export ADWORDS4R_DEBUG=TRUE +or from your Ruby code: +ENV['ADWORDS4R_DEBUG'] = 'TRUE' +This will output the SOAP XML to stderr, which will usually show up in your +terminal window. +There's also the option of logging requests and XML to files. In order to enable +this, you should use the write_to_file method of the loggers inside your +AdWords::API object: +adwords = AdWords::API.new +adwords.unit_logger.log_to_file +adwords.xml_logger.log_to_file + +The first logs the units spent and the requests made, whereas the second logs +the full SOAP XML being sent and received over the wire. These will be written +to the current directory by default, but you can specify a path as an optional +parameter to log_to_file: +adwords.unit_logger.log_to_file('/var/log/my_app') +adwords.xml_logger.log_to_file('/var/log/my_app') + +The files will be named request_info and soap_xml, respectively. + + Docs for Developers ------------------- rake getwsdl to get the wsdl files rake generate to regenerate the bindings if needed rake package to package the gem and create a release - + Copyright/License Info ---------------------- -Copyright 2008, Google Inc. All Rights Reserved. +Copyright 2009, Google Inc. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at