Developer Documentation

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 here:

Once you’ve registered a domain name in your CloudSponge account you’ll be given a domain key that we'll refer to as "YOUR_DOMAIN_KEY" in the rest of this documentation.

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 -->
  var csPageOptions = {
  <script src=""></script>

Internet Explorer Caveat: Please be aware of IE's Protected Mode settings. Your test page and both need to be in zones with the same Protected Mode setting. Usually, is in the Internet Zone, and your localhost is in the Local internet Zone.

Our recommendation is to enable Protected Mode for both the Internet Zone and the zone that your test page is in. This ensures that your local environment behaves the same as in production.

This is not typically an issue in production since both sites are in the same IE zone and will be treated with the same Protected Mode.

Deep Links

The Basic Installation code above puts an "Add from Address Book" hyperlink on your page that will open our widget to a menu of available contact sources.

If you'd like to skip the menu (and eliminate one click for your users) you can use Deep Widget Links instead:

The hyperlinks in the code sample above are basic text; since you are adding this code, you can add css styling and images to suit your site.

You may download a zip file of the icon set below for you if you'd like to use what we're using.

Customization Options

You may specify any of the following variables in your csPageOptions hash.

Variable Type Default Usage
cache_contacts boolean true When this value is true, a cached copy of the user's contacts will be displayed without prompting the user to provide consent again, if the contacts are available. When set to false, the user will always be prompted to import their contacts, even if they have recently imported. If your users commonly access your site from a public location, like a library, you may want to specify false for this value.
displaySelectAllNone boolean true When true, enables the 'All' and 'None' links on the Select Your Contacts page which allow the user to select or de-select all their contacts with a single click. When false, these links are hidden.
include array ['email','name'] Indicates the data to include when automatically populating the contacts in the textarea. When 'name' is included, then both the name and the email address are set in the textarea in the format name <email>. When 'name' is not included, then only the email addresses are set and no additionally formatting is applied. When 'mailing_address' is included in the array, these will be included with the JSON data passed into the callback methods (example). See here for the format of the contacts array.
initiallySelectedContacts boolean false Indicates the initial state of the checkboxes associated with each contact.
force_mobile_render boolean false When this value is true the widget renders itself with the mobile frame and content. Overrides the widget's own user-agent detection.
mobile_render boolean false When this value is true and the the widget is viewed on a mobile device the widget renders as a mobile browser optimized version. This option should only be set to true when the page that hosts the widget is also optimized for a mobile browser. Doing otherwise may cause improper scaling on the widget making it unusable. Currently only iOS devices are supported with this feature.
selectionLimit integer null When defined limits the number of contacts that can be selected in the list. Specify a value for selectionLimitMessage to set a custom message. Use with displaySelectAllNone:false.
selectionLimitMessage string null Specifieds the message to display to the user in an alert box when they attempt to select too many contacts. Ignore it to suppress the message. Has not effect unless used with selectionLimit.
sources array ['yahoo', 'gmail', 'windowslive', 'aol', 'plaxo', 'addressbook', 'outlook'] Specifies the sources to display on the contact sources page.
performEmailValidation boolean true When true, the widget only displays and returns valid SMTP email addresses. This will filter Exchange addresses. Uses the regexp: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i
ignoreMultipleEmails boolean false When true, the widget only displays the first email address when a contact has multiples.
skipSourceMenu boolean false You can suppress the display of the Choose Your Address Book page which will hide the 'Back' links. The widget will close instead of displaying this page, unless you call cloudsponge.launch() with no arguments.
stylesheet string Specifies a URL to a stylesheet to override the default so that you can make our widget match your website. This URL is included instead of the default widget stylesheet. We recommend using the default stylesheet as a template for your copy.
This feature must be enabled by a CloudSponge administrator, please email to request permission.
textarea_id string The ID of the textarea to automatically populate with a list of the contacts. If this value is unset or invalid, then automatic population of contacts is disabled and the contacts should be received by one of the callback functions described below.

Javascript Callbacks

You may define any of the following functions in your csPageOptions hash.

Function Usage
Called immediately after the widget is completely initialized and any links to launch the widget can be safely enabled. If your page is launching the widget programatically via the widget API, then ensure that you watch for this callback before attempting to launch the widget.
Called immediately before the widget is launched either by the user clicking a "cs_import" link or programatically by calling cloudsponge.launch(). If the callback function returns false, then the widget will cancel launching. If the widget has not been initialized, the callback will not be called. No parameters are passed to the callback.
Called after the widget launches and all UI elements have been created on the page, but the widget content is loaded. No parameters are passed to the callback. This callback can be useful for overriding some css styles on the floatbox container. Example
Called immediately after the user finishes any authentication/consent and before CloudSponge begins to import the concats. The source of the contacts is passed into the callback.
afterImport(source, success)
Called after CloudSponge completes importing the users contacts. The source of the contacts and a boolean value indicating if the import succeeded (true indicates a successful import) are passed into the callback. Example
beforeDisplayContacts(contacts, source, owner)
Called before the Choose Your Contacts page renders. The callback may accept array of contacts, the name of the source of the contacts, and the owner contact. Since this callback occurs before the contacts are displayed and the user has the opportunity to filter them, all the contacts if the user's address book are passed in at this point. These contacts are not guaranteed to have any email addresses. Returning false from this function will immediately cause the widget to close, thus suppressing the display of the Choose Your Contacts page. Example
afterSubmitContacts(contacts, source, owner)
Called after the user clicks the Next button on the Choose Your Contacts page and before the widget overlay is dismissed. The callback may accept array of contacts, the name of the source of the contacts, and the owner contact. Only the contacts that the user selected are passed to the function. All these contacts will have at least one email address. Example
Called just before the widget closes for any reason. No data is passed into the beforeClosing function.
Called just after the widget closes for any reason. No arguments are passed into function.

Javascript API

When you include our address_book.js script on your page, we'll instantiate a Javascript object named cloudsponge. This is a global object and only one instance is permitted on a page.

cloudsponge Functions
Function Usage
cloudsponge.init(options) This function may be called before the widget is used, as an alternative to declaring the var csPageOptions. If you want to dynamically change the csPageOptions, cloudsponge.init(..) can be called to update the csPageOptions. Valid keys and values for options are referenced in the widget customization options above.
cloudsponge.launch(source) example cloudsponge.launch launches the widget. This function does nothing if the widget has not yet completed initialization. This is a handy function for launching the widget on a page load, or when more flexibility is required for starting the import. Passing in a source is optional: when omitted, the widget displays the list of contact sources; when a valid source is specified, the action launches directly to the specific import. Valid sources are: 'yahoo', 'gmail', 'windowslive', 'aol', 'plaxo', 'addressbook', 'outlook'.

The CloudSponge Widget uses an array of Contact objects to represent a user's address book.

Contact Properties
Property Description
contact.first_name The contact's first name.
contact.last_name The contact's last name. An array of Email objects for the contact. An array of Phone objects for the contact.
contact.address undefined or an array of Address objects for the contact. Each address has the properties: address and type.
Contact Functions
Function Usage
contact.fullName() Returns a string with the first and last name for the contact joined with a space.
contact.primaryEmail() Returns a string with the primary email address for the contact.
contact.selectedEmail() Returns a string with the email address that was selected in a drop down list. If the Choose Contacts page was not displayed, it returns the value of contact.primaryEmail().

Email addresses are represented by an object with an address and type.

Email Properties
Property Description
email.address The email address.
email.type The type associated with the email. Possible values depend on the address book source.

Phone numbers are represented by an object with a number and type.

Phone Properties
Property Description
phone.number The phone number.
phone.type The type associated with the phone. Possible values depend on the address book source.

Mailing addresses are represented by an object with address sections and a type.

Mailing Address Properties
Property Description
address.formatted undefined or the full mailing address, formatted with line breaks (\n).
address.street The street portion of the mailing address. The city portion of the mailing address.
address.region The state or province portion of the mailing address. The city portion of the mailing address.
address.postal_code The zip or postal code portion of the mailing address.
address.type The type associated with the mailing address. Possible values depend on the address book source.

Using the Widget From An iframe

When your page displays the link to launch the widget on an iframe, you may need to separate the initialization code from the javascript includes. The widget adds 2 of its own iframes to the page where the snippet is included. This may lead to cases where conflicts between libraries and iframe setup can prevent the proper initialization of the widget. Further, the overlay will fill only the iframe that it is loaded on, so if you attempt to launch the widget on a small iframe, it will limit the size of the widget interface which may not be the desired user experience.

To resolve this issue, split the widget initialization and handling code between the parent and child frames on your page. The parent frame is responsible for initializing the widget and handling callbacks. The child frame contains the link to launch the widget.

Here is a trial example demonstrating the mechanics of this pattern. A parent page might look like this:

And here is a child iframe that just contains the link to launch the widget:

If you wish to display the widget inside an iframe without communicating with the parent, you need to add a value to the csPageOptions.