h1. This client library has been deprecated.
h3. This library will no longer be supported and does not support OAuth2.
h1. AWeber API Gem "!https://secure.travis-ci.org/aweber/AWeber-API-Ruby-Library.png?branch=master!":http://travis-ci.org/aweber/AWeber-API-Ruby-Library
Official AWeber API gem.
h2. Installation
@gem install aweber@
h2. Getting Started
This guide assumes you have nothing previously setup to work with the AWeber API. It will walk through registering an account, creating an app and everything up to the point where you'll actually start working with data.
If you don't want to bother with all the account setup stuff, you can look in the "examples":https://github.com/aweber/AWeber-API-Ruby-Library/tree/master/examples directory for just example code.
Requires a normal AWeber account (not a Labs account)
h3. 1. Register an AWeber Labs Account
Head to "http://labs.aweber.com":http://labs.aweber.com and sign up for a free AWeber Labs account. This is how you register apps and get OAuth keys.
h3. 2. Create an App
Once logged in, Create a New App. Once created, it will show you the Consumer Key and Secret for that app.
h3. 3. Write Some Code
h4. The OAuth Handler
bc. oauth = AWeber::OAuth.new('consumer_key', 'consumer_secret')
h4. Authorize an Account
Open, what the following outputs, in a browser and use your AWeber account credentials. This will give your app permission to work with your account's data:
bc. oauth.request_token.authorize_url
A callback url may also be passed by setting the :oauth_callback parameter:
bc. oauth.request_token(:oauth_callback => 'http://www.example.com').authorize_url
h4. Verification Code
After you do the above step, it will output a "Verification Code". Copy this and verify your @oauth@ object:
bc. oauth.authorize_with_verifier('verification_code')
h4. Grab an AWeber::Base
bc. aweber = AWeber::Base.new(oauth)
This object is how you access data from your account. @aweber.account@ is your account object which is the stem for all other resources.
h4. What if I don't want to verify every time?
After verifying once, the @oauth@ object contains an @oauth.access_token.token@ and and @oauth.access_token.secret@ which may be used to authorize your application without having to verify via url:
bc. ... oauth.authorize_with_verifier('verification_code') puts 'Access token: ' + oauth.access_token.token puts 'Access token secret: ' + oauth.access_token.secret
The token and secret can then be saved, and authorization can be performed as follows:
bc. require 'aweber' oauth = AWeber::OAuth.new('consumer_key', 'consumer_secret')
oauth.authorize_with_access(YOUR_ACCESS_TOKEN, YOUR_ACCESS_TOKEN_SECRET) aweber = AWeber::Base.new(oauth)
h3. I want to distribute my app as a public app
If you intend to distribute your app to many AWeber customers via source code ("See here for more info":https://labs.aweber.com/getting_started/main#app_type), you will want to use the app id to authenticate your app as follows.
h4. Build the authorize_app url:
bc. require 'aweber' app_id = '1XXXXXXX8' #paste you app id from labs.aweber.com here auth_url = 'https://auth.aweber.com/1.0/oauth/authorize_app/' + app_id puts "please go to " + auth_url
h4. Verification Code
After you do the above step, it will output a “Verification Code”. Copy this into @authorize_with_authorization_code@
bc. aweber = AWeber::Base.authorize_with_authorization_code('My|Authcode|Pasted|Here')
You can now use the aweber object to access data from the account that authorized your app!
h2. Usage
h3. Resource Traversal
Getting resource data is much like traversing associations in ActiveRecord. Everything starts with the @account@ object and goes from there:
bc.. aweber.account.lists #=> #
h3. Collections
@aweber.account.lists@ in the example above would be a Collection. Collections act like a normal Hash. Resources of a collection are accessed normally, using @[]@ with the key being the ID of the resource.
h4. findby*
Collections also support ActiveRecord style @findby*@ methods:
bc. aweber.account.lists.find_by_name("testlist")
h3. Resources
Resources are elements of a Collection. A single list resource would be retrieved with:
bc. aweber.account.lists[1234]
h3. Why can't I access the subscriber data?
If you are unable to access the data associated with your subscribers, it is likely that you have not enabled subscriber access permissions for your application. To do so, follow the directions at: https://labs.aweber.com/docs/permissions. These changes won't take effect until you renew your access tokens.
h2. Updating Resources
Currently, subscribers are the only resource you can update via the API. Everything else is read only for the time being.
h3. Updateable Subscribers
h3. Moving Subscriber From List to List
bc. new_list = aweber.account.lists[1234] subscriber.list = new_list
h3. Example
bc. subscriber = account.lists[654321].subscribers[123456] subscriber.name = "New Name" subscriber.save
h2. Adding Subscribers
bc. new_subscriber = {} new_subscriber["email"] = "fake@example.com" new_subscriber["name"] = "My New Subscriber" aweber.account.lists.find_by_name("mylistname").subscribers.create(new_subscriber)
h2. Note on Patches/Pull Requests
h2. Copyright
Copyright (c) 2010-2013 AWeber Communications, Inc. See LICENSE for more detail.