Cloudsponge

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:

https://www.cloudsponge.com/test-drive

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 -->
<script>
var csPageOptions = {
  domain_key:"YOUR_DOMAIN_KEY",
  textarea_id:"contact_list"
};
</script>
<script src="https://api.cloudsponge.com/address_books.js"></script>

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.
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 support@cloudsponge.com 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
afterInit()	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.
beforeLaunch()	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.
beforeImport(source)	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
beforeClosing()	Called just before the widget closes for any reason. No data is passed into the beforeClosing 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.
contact.email	An array of Email objects for the contact.
contact.phone	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.
address.city	The city portion of the mailing address.
address.region	The state or province portion of the mailing address.
address.country	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.