CloudSponge Contact Importer

Last Updated: 24 October 2014

The CloudSponge Contact Importer is a Heroku add-on to import address books from Yahoo, Hotmail, Windows Live/MSN, Gmail, AOL, Outlook and the Mac OS X Address Book.

You can use these email addresses to invite Friends, find Friends, or whatever other application you need.

The simplest way to use CloudSponge is using the JavaScript widget importer with our default snippet: it will add an “Add from Address Book” link to your email form, allowing the user to click, select an address book provider (Gmail, Yahoo, Hotmail, Windows Live, etc.) and then select contacts to automatically fill your email recipient field.

You can see it in action on our test drive page.

Additionally, our HTML widget importer can easily be plugged into your website in less than 5 minutes, just using a simple copy/paste.

Later, you can replace our branding with your own company name in addition to several other customization options. You can even use one of supported APIs to take full control of the importer process.

Provisioning the add-on

The CloudSponge Contact Importer can be attached to a Heroku application via the CLI:

$ heroku addons:add cloudsponge
-----> Adding cloudsponge to sharp-mountain-4005... done, v18 (free)

Once it has been provisioned, a CLOUDSPONGE_KEY setting will be available in the app configuration and will contain your Account Key. This can be confirmed using the heroku config:get command.

$ heroku config:get CLOUDSPONGE_KEY
1234

After installing CloudSponge, the application should be configured to fully integrate with the add-on.

Because your CLOUDSPONGE_KEY is generated asynchronously after the addon has been provisioned, there will be a short delay before it is available. If you get an empty value for CLOUDSPONGE_KEY, wait a moment and try again.

Local setup

At Heroku, the config var CLOUDSPONGE_KEY is now automatically filled after install. In this sample, our CLOUDSPONGE_KEY is 1234.

You can now simulate the same Heroku behavior in your local environment, specifying your key when running the application (or any other command) by prepending the shell command:

$ CLOUDSPONGE_KEY="1234" rails s

If you need a different way to setup your local config vars, visit the Heroku article about config vars.

Now it’s time to setup your importer.

Setup The Contact Importer Widget

Our Contact Importer Widget is appropriate for developers who want to get up and running quickly. You can see it in action on our test drive page.

Basic installation

This is all you need to get started with CloudSponge, everything else is optional:

<!-- Any link with a class="cs_import" will start the import process -->
<a class="cs_import">Add from Address Book</a>

<!-- This textarea will be populated with the contacts returned by CloudSponge -->
<textarea id="contact_list" style="width:450px;height:82px"></textarea>

<!-- Include these scripts at the bottom of your page to import address books with CloudSponge -->
<script>
var csPageOptions = {
  domain_key:"<%= ENV['CLOUDSPONGE_KEY'] %>",
  textarea_id:"contact_list"
};
</script>
<script src="//api.cloudsponge.com/address_books.js"></script>

This example of config vars is using Ruby ERB file. You can use any other template, or any other language. Just replace this line…

domain_key:"<%= ENV['CLOUDSPONGE_KEY'] %>",

… with the proper way your language/template handle the output inside HTML.

For more advanced widget options, please, see the online documentation.

Customization

The user experience is fully customizable to suit your needs.

The CloudSponge widget’s look and behaviour can be customized in many ways to blend in with your application. Read more about our current widget customizations in our documentation.

The user experience can also be white-labeled so that your users don’t see the CloudSponge brand anywhere. You can read more about this advanced topic on our online documentation.

Our server API eases the burden of maintaining multiple provider integrations while giving you full control over every pixel of the user experince.

Dashboard

The CloudSponge Contact Importer dashboard allows you to add new domains, manage account users and check address books import statistics.

The dashboard can be accessed via the CLI:

$ heroku addons:open cloudsponge
Opening cloudsponge for sharp-mountain-4005…

or by visiting the Heroku Dashboard and selecting the application in question. Select CloudSponge Contact Importer from the Add-ons menu.

Adding a new domain

If you Heroku app has a top level domain, like example.com, you can add this domain to CloudSponge.

First, open CloudSponge Dashboard:

$ heroku addons:open cloudsponge
Opening cloudsponge for sharp-mountain-4005…

Then, at Dashboard, click on “Add Domain” button and follow the 4 step process.

And that’s it! You don’t need to change your code: it’ll automatically work for the new domain.

Removing the add-on

The CloudSponge Contact Importer can be removed via the CLI.

$ heroku addons:remove cloudsponge
-----> Removing cloudsponge from sharp-mountain-4005... done, v20 (free)

Support

Heroku support should be sent via Heroku Support channels. CloudSponge Contact Importer related issues or product feedback is welcome at support@cloudsponge.com.