Fetch users' contact lists without asking them to provide their passwords, as painlessly as possible.

Contacts provides adapters for:

• Google
• Yahoo!
• Windows Live

First, register your application with the service providers you require. Instructions below under "Setting up your accounts".

Now, create a consumer:

consumer = Contacts::Google.new
consumer = Contacts::Yahoo.new
consumer = Contacts::WindowsLive.new
# OR by parameter:
# provider is one of :google, :yahoo, :windows_live
consumer = Contacts.new_consumer(provider)

Now, direct your user to:

consumer.authentication_url(return_url)

return_url is the page the user will be redirected to by the service once authorization has been granted. You should also persist the consumer object so you can grab the contacts once the user returns:

session[:consumer] = consumer.serialize

Now in the request handler of the return_url above:

consumer = Contacts.deserialize(session[:consumer])
if consumer.authorize(params)
  @contacts = consumer.contacts
else
  # handle error
end

Here, params is the hash of request parameters that the user returns with. consumer.authorize returns true if the authorization was successful, false otherwise.

The list of @contacts are Contacts::Contact objects which have these attributes:

• name
• emails

Set up your projects here.

• When redirecting to an unverified domain (e.g., localhost), the user sees a warning when authorizing access.

What this means:

• You can use the same consumer key for development as production.

Set up your projects here

• When a project's domain is verified, you must redirect to it.
• When a project's domain is not verified, you can redirect anywhere, and the user sees a warning when authorizing access.

What this means:

• Set up separate production and development projects.
• Verify the domain of your production project. You will only be able to redirect to your production domain when using this key.
• Don't verify the domain of your development project. You will be able to redirect to any domain when using this key.

Set up your projects here.

• There is no domain verification step.
• The domain cannot be localhost, an IP address, or have a query string.
• You must redirect to the project's domain, on any port, and the URL may not have a query string or fragment.
• You must specify a privacy policy URL.

What this means:

• Set up separate production and development projects.
• For development, use a domain like myapp.local.
• Map this domain to 127.0.0.1 in /etc/hosts or a local DNS server.
• If you want to run your app on a different domain (e.g., localhost:3000), redirect the POST from Windows Live to a GET on the original domain. This ensures the popup window has the same origin as the opener page, in accordance with browser same origin policies.

Copyright (c) 2010 George Ogata See LICENSE for details.

Derived from Mislav's Contacts, Copyright (c) 2009 Mislav Marohnić