CloudSponge

With the release of our new widget, our developer documentation has changed! Find the complete documentation for our old widget here.

Getting Started

Introduction to CloudSponge

Making your users type their friends email addresses into your refer-a-friend form is a friction point that we’re in business to help you with. Our list of supported address books is growing every week, send us an email if you don’t see one that’s important to you.

The first step is to create your company’s CloudSponge account or get an invitation to your company’s account if someone else already created it.

Once you can log into your account, you’ll see your company’s Universal Snippet that will add our widget to any site you use it on. Everything else you need to know is right here in the developer documentation.

If you’d rather build a completely custom interface, you’re welcome to integrate with our REST API instead of using our widget.

Both options allow you to remove the CloudSponge branding in addition to several other customization options.

No Development Environment Handy? No Problem!

Check out our guide to Getting Started Without a Development Environment.

JavaScript Widget

Our JavaScript widget is the best way to get up and running quickly. You can see it in action on our Test Drive page.

If you don’t like the default style or behavior, read on.

• Don’t like our colors, fonts, corner radiuses, etc? Override our CSS with your own.
• Prefer to use your own brand in OAuth dialogs? Use your own consumer credentials.
• Don’t like a feature in our widget’s UI? Turn if off with JavaScript options.
• Need special behavior in the widget flow? Use our JavaScript callbacks.
• Don’t like the widget, period? Use our REST API and build your own.

The widget is installed on thousands of websites so the chances are pretty good that you’re not the first person to need whatever you have in mind. If you’re not sure how to get it to do what you want, just write us an email and we’ll help you figure it out.

Basic Installation

Once you’ve created a CloudSponge account, you’ll get your own Widget Snippet that you can add to any page to include our widget there. The snippet is a very basic example of using our widget on a page. It does three things that any widget integration must do:

1. include your widget javascript,
2. provide a way for the end user to launch the widget and,
3. do something with the user’s contacts.

1. Add your script.

Your CloudSponge key is the name of your own custom widget script. Add this script to your site in the head of the page.

<script src="//api.cloudsponge.com/widget/YOUR_WIDGET_KEY.js"></script>

2. Launch the Widget:

Launch the widget and let users pick a source from our UI:

<a class="cloudsponge-launch">Add From Address Book</a>

Or display your own “deep links” to launch directly to a specific address book:

<a class="cloudsponge-launch" data-cloudsponge-source="gmail">Gmail</a>

Read more about our linking options below.

3. Get the Contacts

After users pick their contacts, they will be populated inside an HTML element.

<input type="textarea" class="cloudsponge-contacts"/>

This is the pattern you’ll follow to get started with CloudSponge. You need to sign in to get your own WIDGET_SCRIPT:

Internet Explorer Caveat

Please be aware of IE’s Protected Mode settings. Your test page and api.cloudsponge.com both need to be in zones with the same Protected Mode setting. Usually, api.cloudsponge.com 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 an issue in production since both sites are in the same IE zone and will be treated with the same Protected Mode.

Linking Options

Once you’ve got our JavaScript loading on the page, the next important step is figuring out how your user is going to invoke the widget. There are two approaches:

1. The default menu link that’s just a simple anchor tag that opens the widget’s main menu.
2. Deep links that skip the menu and jump straight to a contact source.

Menu Link

In step 3 above, the Basic Installation code puts an “Add from Address Book” hyperlink on your page that will open our widget to a menu of available contact sources. This is the simplest way to get started. If you want to sort or filter the contact source icons that are displayed on the main menu, use the sources parameter in your csPageOptions.

For example, if you want to display Gmail, Yahoo, LinkedIn, iCloud and OS X Contacts (in that order) then:

window.csPageOptions = {
  sources: ["gmail", "yahoo", "linkedin", "icloud", "addressbook"]
}

Deep Links

In step 3 above, the Basic Installation code 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 can find several file formats for the icons we’re using plus a couple more styles on IconFinder.

Custom Stylesheets

Our widget is fully customizable via CSS styles. Use the css option to link to your own copy of our widget stylesheet. The stylesheet that you include needs to only define the styles you want to override. Here are examples of common changes that you might want to make. If there anything you want to style that’s not included, let us know and we’ll help you with the particulars.

This feature is part of our Standard Plan features and must be enabled by a CloudSponge administrator, please email support@cloudsponge.com to request permission.

Complete Reference

Options

Options should be set by calling cloudsponge.init(options). Supported options are listed below.

Older versions of the widget supported the following options which have been deprecated:

Older versions of the widget supported the following options which have been disabled:

Find the complete documentation for our old widget here.

Custom Scripts

You can add your own scripts to the widget, to be loaded on each view of the widget. Reach out to us for more information.

JavaScript Callbacks

You may define any of the following callback functions using cloudsponge.init:

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.

WebHooks API

Use our webhooks to have our widget POST address book data to any URL you choose. You might send the content to your own server or to a service like Zapier to handle the data on your behalf.

NB Be careful not to expose any private or secure data (like basic authentication) in the webhook URL. This URL is set in the CloudSponge object’s options and will be exposed in public.

To specify a webhook, add it to your call to cloudsponge.init. For example:

cloudsponge.init({
  webhooks: {
    // send the entire address book before it is displayed to the user
    beforeDisplayContacts: 'https://example.com/path/to/before/webhook/',
    // send the contacts that the user selected and submitted
    afterSubmitContacts: 'https://example.com/path/to/after/webhook/'
  }
})

Available webhooks:

Our webhooks send this payload structure:

{
    "contacts": [arrayOfContacts],
    "source": stringSource,
    "owner": ownerContact
}

The value of stringSource indicates the source of the address book. It will be one of the codes from our list of supported soures. arrayOfContacts and ownerContact both follow our standard contact data structure.

Data Structure

The CloudSponge Widget uses an array of Contact objects to represent a user’s address book. This data structure is most commonly used by developers who implement the beforeDisplayContacts() and afterSubmitContacts() callbacks since it’s passed in as an argument there.

Sample Code

• What is the basic widget code?

  The following sample code shows all you need to get started with CloudSponge. Everything else is optional. For more information see Basic Installation.

• How do I use 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:

• How can I make the widget return only plain email addresses?

  You can have the widget return a list of plain email addresses, excluding the names. The emails will be in the format contact@domain.com, instead of contact_name <contact@domain.com>

• How is it possible to filter contacts from the host page?

  You cannot apply a filter to the contacts displayed in the widget, but you can render the contacts on your own page before they display to the user. You can implement the beforeDisplayContacts callback in order to get all the contacts of the user’ address book before they are displayed. Return false from this callback to suppress the display of the “Choose Your Contacts” screen.

• How do I handle multiple text areas for email addresses?

  You can update the cloudsponge options at run-time to reflect which textarea to put the contacts into.

• How do I set up the applet HTML tag?

  Here’s a partial HTML that would require replacing the values in curly braces {} with the values returned by our API.

• I’ve done the applet branding steps, how do I get the widget to use my version of the applet?

  You’ll need to pass the URL to your hosted version of the applet in the csPageOptions as demonstrated below.

• How do I know when the import completes and if it was successful?

  The afterImport callback will let you know!

• I want every contact, not just the ones that the user selects. How can I get them all?

  Here is a sample code for the beforeDisplayContacts callback.

• I don’t like the way the widget formats the contacts. How can I do it myself?

  The afterSubmitContacts callback is for you. This callback is invoked after the user clicks the Next button on the Choose Your Contacts page and before the widget overlay is dismissed. The callback receives the array of selected 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. If the user abandons the import process, this callback will not be invoked.

• How do I suppress the ‘All’ and ‘None’ links on the contacts form?

  There’s a simple displaySelectAllNone option for that.

• How can I make all contacts selected by default?

  There’s a simple initiallySelectedContacts option for that.

• I don’t want all the sources to be displayed or I want to change their order. Can I do that?

  Yes! Use the option to filter the sources we display, or reorder them how you like.

• How can I include mailing addresses in contacts data?

  Use the include option and add ‘mailing_address’ to the list. The returned contacts will have either an undefined value for address or an array of that contact’s mailing addresses.

REST API

CloudSponge offers its very own RESTful Address Book API to connect your web application to the contact sources. Use this method if you want to provide a user experience that is not supported by our widget interface.

Despite there being three different user authentication methods, importing contacts with the API follows a similar 3-stage asynchronous process.

Step 1: Get Permission - Your application initiates an address book import by calling the “Begin Import” URL, specifying the user authentication method, the address book source, plus any other additional information required. The API returns a result object containing a unique identifier for subsequent calls to the API, and in some cases data needs to be displayed in the user’s browser.

Step 2: Wait For Import - Your application polls the “Events” URL and receives a result object indicating the current Import Events. These events notify you of the current progress of the import, if any errors have occurred, or when the import is complete. You can optionally display these Import Events to the user’s browser.

Step 3: Download - Once you have received a successful “complete” Import Event, you can retrieve the contacts payload from the API directly or from a database configured for your account.

Step 1: Get The User’s Permission

This step is a little different depending on which source your user wants to import from.

Which import method should I use?

The table below summarizes which import method to use with each source. Desktop imports use a different import method depending on the configuration of the end user’s system.

Begin User Consent Import (OAuth, OAuth2.0, CSV and VCard)

This import method will send your user to a new window to grant permission to access their contacts. You will call our API to get the URL that you need to load in this window.

1. Your application launches a new popup window to accommodate for the user consent URL.
2. Once the popup launches, your application calls the /begin_import/user_consent endpoint, including the contact source requested.
3. CloudSponge returns a result object, including the import_id to use to fetch the contacts later and a url for the user consent page, which needs to be displayed to the user in the popup window.
4. Your application redirects the popup to the consent page url.

Now your application’s main page should go to Step 2 while the user gives CloudSponge permission to access their contacts and we download their address book for you.

Definition

POST https://api.cloudsponge.com/begin_import/user_consent[.format]

Request Arguments

Example Request

curl --user 33664218758c5244136965160db455db012b1411:Tpa01z+vVPE7MxXi \
     --request POST \
     --data "service=yahoo" \
     --url "https://api.cloudsponge.com/begin_import/user_consent.json"

Response Variables

Example Response (JSON)

{  
  "status": "success",
  "url": "https://api.cloudsponge.com/n/FULNW3D",
  "import_id": 1126
}

Example Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>success</status>
  <url>https://api.cloudsponge.com/n/FULNW3D</url>
  <import-id>1126</import-id>
</result>

Begin Username/Password Import

This import method requires that you collect your user’s username and password for their address book service.

1. Your application collects the user’s username and password combination for the contact source requested.
2. Your application calls the /begin_import/import endpoint, including the username/password plus the contact source requested.
3. CloudSponge returns a result object indicating the request has been received and specifying an import_id for fetching events and contacts later.
4. (Optional) Your application displays a status update to the user.

Now your application should go to Step 2 while CloudSponge downloads the address book for you.

Definition

POST https://api.cloudsponge.com/begin_import/import[.format]

Request Arguments

Example Request

curl --user 33664218758c5244136965160db455db012b1411:Tpa01z+vVPE7MxXi \
     --request POST \
     --data "service=icloud" \
     --data "username=foo" \  
     --data "password=bar" \
     --url "https://api.cloudsponge.com/begin_import/import.json"

Response Variables

Example Response (JSON)

{  
  "status": "success",  
  "import_id": 1126  
}

Example Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>success</status>
  <import-id>1126</import-id>
</result>

Begin Applet Import

This import method requires that your user grants our applet permission to access the contacts that are stored locally on her computer.

1. Your application calls the /begin_import/desktop_applet endpoint, including the contact source requested.
2. CloudSponge returns a result object, including a url for the desktop applet, which needs to be downloaded by the user and an import_id to be used to identify the import to the applet and to fetch the events and contacts.
3. Your application directs the user’s browser to download the applet from the url provided. This is accomplished by inserting the url and import_id into the HTML snippet at the bottom of this section and rendering it onto the page.

Now your application should go to Step 2 while the user gives CloudSponge permission to access their address book and we download it for you.

Definition

POST https://api.cloudsponge.com/begin_import/desktop_applet[.format]

Request Arguments

Example Request

curl --user 33664218758c5244136965160db455db012b1411:Tpa01z+vVPE7MxXi \
     --request POST \
     --data "service=outlook" \
     --url "https://api.cloudsponge.com/begin_import/desktop_applet.json"

Response Variables

Example Response (JSON)

{  
  "status": "success",
  "url": "https://api.cloudsponge.com/objects/ContactsApplet_signed.jar",
  "import_id": 1126  
}

Example Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>success</status>
  <url>https://api.cloudsponge.com/objects/ContactsApplet_signed.jar</url>
  <import-id>1126</import-id>
</result>

Insert the url and import_id values into the relevant spots in the HTML below and render it on your page to invoke the applet.

Please note Chrome no longer supports the Java browser plugin so when importing from Outlook or Mac OS X contact on Chrome, use the file upload or iCloud import instead.

<!--[if !IE]> Firefox and others will use outer object -->
<object classid="java:ContactsApplet"
  type="application/x-java-applet"
  archive="[ url ]"
  height="1"
  width="1">
  <!-- Konqueror browser needs the following param -->
  <param name="archive" value="[ url ]" />
  <param name="importId" value="[ import_id ]"/>
  <param name="cookieValue" value="document.cookie"/>
  <param name="MAYSCRIPT" value="true">
<!--<![endif]-->

  <!-- MSIE (Microsoft Internet Explorer) will use inner object -->
  <object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    codebase="http://java.sun.com/update/1.6.0/jinstall-6u30-windows-i586.cab"
    height="0"
    width="0" >
    <param name="code" value="ContactsApplet" />
    <param name="archive" value="[ url ]" />
    <param name="importId" value="[ import_id ]"/>
    <param name="cookieValue" value="document.cookie"/>
   <param name="MAYSCRIPT" value="true">

    <!-- Chrome falls through to this innermost applet -->
    <applet archive="[ url ]" code="ContactsApplet" height="1" width="1" MAYSCRIPT>
      <param name="importId" value="[ import_id ]"/>
      <param name="cookieValue" value="document.cookie" />
      <param name="MAYSCRIPT" value="true">
      <strong>
        This browser does not have a Java Plug-in.<br />
        <a href="http://java.sun.com/products/plugin/downloads/index.html">
          Get the latest Java Plug-in here.
        </a>
      </strong>
    </applet>
  </object>

<!--[if !IE]> close outer object -->
</object>
<!--<![endif]-->

Step 2: Wait For The Import To Finish

After a contact import is initiated, your application must monitor the events as they are generated from CloudSponge. Use the import_id value that was returned from the call to begin_import to identify the import request to CloudSponge when fetching events.

1. Your application calls the /events URL to get the current Import Events, specifying the import_id returned in the initial request.
2. CloudSponge returns the current Event result object.

Please Note The value on this endpoint will only update every second at most. Please limit your queries here to once per second.

Definition

GET https://api.cloudsponge.com/events/[import_id][.format]

Request Arguments

Example Request

curl --user 33664218758c5244136965160db455db012b1411:Tpa01z+vVPE7MxXi \
     --url "https://api.cloudsponge.com/events/1126.json"

Response Variables

Example Response (JSON)

{
  "events": [
    {
      "value": 0,
      "status": "COMPLETED",
      "event_type": "INITIALIZING"
    },
    {
      "value": 2,
      "status": "COMPLETED",
      "event_type": "GATHERING"
    },
    {
      "value": 0,
      "status": "COMPLETED",
      "event_type": "COMPLETE"
    }
  ],
  "echo": null,
  "user_id": "myUserId_0003",
  "import_id": 1126  
}  

Example Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
<eventsResponse>
  <events type="array">
    <event>
      <event-type>INITIALIZING</event-type>
      <status>COMPLETED</status>
      <value type="integer">0</value>
    </event>
    <event>
      <event-type>GATHERING</event-type>
      <status>COMPLETED</status>
      <value type="integer">2</value>
    </event>
    <event>
      <event-type>COMPLETE</event-type>
      <status>COMPLETED</status>
      <value type="integer">0</value>
    </event>
  </events>
  <echo nil="true"></echo>
  <user-id>myUserId_0003</user-id>
  <import-id>1126</import-id>
</eventsResponse>

API Events

The following table defines the events array elements. Please note that the XML response will have some extra fields included, we do not recommend that you write your code to depend on these fields since we are in the process of deprecating them.

API Error Codes

The following table defines all of the error codes that you can expect to receive along with status=ERROR elements in the events array.

Step 3: Download The Address Book

When the COMPLETE event is received with the COMPLETED status in Step 2, your application should retrieve the contacts immediately. After a few minutes, they will be deleted from CloudSponge.

1. Your application calls the /contacts endpoint to retrieve the contacts, specifying the import_id from the initial request.
2. CloudSponge returns the Contacts result object in the format requested.

Definition

GET https://api.cloudsponge.com/contacts/[import_id][.format]

Request Arguments

Example Request

curl --user 33664218758c5244136965160db455db012b1411:Tpa01z+vVPE7MxXi \
     --url "https://api.cloudsponge.com/contacts/1126.json?start=0&count=10"

Response Variables

Example Response (JSON)

{
  "echo":null,
  "user_id":"myUserId_0003",
  "import_id":1126,
  "start": 0,
  "count": 2,
  "total": 2,
  "contacts_owner":
    {
      "first_name":"Joe",
      "last_name":"Smith",
      "email":[
        {
          "address":"joe@example.com"
        }
      ]
    },
  "contacts": [
    {
      "first_name":"John",
      "last_name":"Doe",
      "phone": [
        {
          "number":"555-1234",
          "type":"Home"
        },
        {
          "number":"555-2468",
          "type":"Work"
        }
      ],
      "email": [
        {
          "address":"johndoe@nowhere.com",
          "type":"Email 1"
        },
        {
          "address":"second@email.com",
          "type":"Email 2"
        }
      ]
    },
    {
      "first_name":"Jane",
      "last_name":"Smith",
      "phone":[
        {
          "number":"555.5678",
          "type":"Home"
        }
      ],
      "email":[
        {
          "address":"janesmith@nowhere.com",
          "type":"Email 1"
        }
      ],
      "addresses": [
        {
          "street":"3450 Sacramento St., #510",
          "city":"San Francisco",
          "region":"CA",
          "country":"US",
          "postal_code":"94118",
          "formatted":"3450 Sacramento St., #510 San Francisco, CA 94118"
        }
      ]
    }
  ]
}

Example Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
<contactsResponse>
  <echo nil="true"></echo>
  <user-id>myUserId_0003</user-id>
  <import-id>1126</import-id>
  <start>0</start>
  <count>2</count>
  <total>2</total>
  <contacts-owner>
    <first-name>Joe</first-name>
    <last-name>Smith</last-name>
    <email type="array">
      <email>
        <address>joe@example.com</address>
      </email>
    </email>
  </contacts-owner>
  <contacts type="array">
    <contact>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <phone type="array">
        <phone>
          <number>555-1234</number>
          <type>Home</type>
        </phone>
        <phone>
          <number>555-2468</number>
          <type>Work</type>
        </phone>
      </phone>
      <email type="array">
        <email>
          <address>johndoe@nowhere.com</address>
          <type>Email 1</type>
        </email>
        <email>
          <address>second@email.com</address>
          <type>Email 2</type>
        </email>
      </email>
    </contact>
    <contact>
      <first-name>Jane</first-name>
      <last-name>Smith</last-name>
      <phone type="array">
        <phone>
          <number>555.5678</number>
          <type>Home</type>
        </phone>
      </phone>
      <email type="array">
        <email>
          <address>janesmith@nowhere.com</address>
          <type>Email 1</type>
        </email>
      </email>
      <address type="array">
        <address>
          <street>3450 Sacramento St., #510</street>
          <city>San Francisco</city>
          <region>CA</region>
          <country>US</country>
          <postal-code>94118</postal-code>
          <formatted>3450 Sacramento St., #510 San Francisco, CA 94118</formatted>
        </address>
      </address>
    </contact>
  </contacts>
</contactsResponse>

API Libraries

We highly recommend that you start by choosing one of the wrappers listed below since most of the hard work is already done, but if you have special needs that aren’t addressed in our wrappers, then feel free to take the do-it-yourself approach.

There are a few open source libraries available, which wrap the API request and response sets into specific programming languages. These may make it easier for you to connect your web application to CloudSponge.

• Ruby

• Java

• PHP

• .Net

• ColdFusion (Contributed by Jojo Serquina, Senior Developer at SignUpGenius.com)

NOTE: These open source libraries have been built by the open source community. We cannot guarantee 100% support for these libraries.

Special Considerations

When building your own custom UX to integrate with our sources, it’s important understand some of the details about some sources so you can help your users be successful.

iCloud

In mid-2017, Apple began to force all 3rd party applications to authenticate using an app-specific password. Since then, CloudSponge has only been able to access iCloud contacts by instructing people to use an app-specific password.

We include the following description in our widget to guide users on creating an app-specific password to share their contacts with us. Your iCloud form should include a similar message to instruct people to create an app-specific password.

Using app-specific passwords
You’ll need to use an app-specific password to sign in to your account to share your contact.
To generate an app-specific password: Sign in to your Apple ID account and follow the steps on your screen.
After you generate your app-specific password, enter or paste it into the password field of the app as you would normally.
Learn more about app-specific passwords.

Replacing CloudSponge OAuth Credentials

Since CloudSponge is the service importing contacts, by default the domain displayed in the user consent window(s) is our domain api.cloudsponge.com. We recognize this may not be an ideal user experience, as your users are unfamiliar with CloudSponge.

CloudSponge offers you the ability customize the user experience with your own company name, domain, logo, fonts, styles, languages and third party OAuth credentials so that your users don’t feel like they’ve left your website.

There are 3 main steps to white labelling imports for Gmail, Yahoo and Outlook.com.

1. Set up a Proxy URL on your domain
2. Create developer accounts with Google, Yahoo! and Microsoft
3. Configure CloudSponge to use your Google/Yahoo/Outlook.com developer credentials (OAuth Credentials)

Set OAuth Credentials in AOL experience is only possible if you have an existing developer relationship with AOL.

The Proxy URL

The OAuth flows provided by Gmail, Yahoo and Outlook.com are designed for a site like yours to request access to a person’s address book. In order for CloudSponge to be able to do the heavy lifting of importing and normalizing the contacts for your site, your application must hand the consent code over to CloudSponge.

You can accomplish this with a special page on your site that we refer to as Proxy URL.

The sole purpose of this page is to accept the token parameters from the contact source (Gmail, Yahoo or Outlook.com) and proxy that to CloudSponge.

Javascript Proxy URL (Recommended)

We have recently released a Javascript Proxy URL implementation that has no server-side dependencies. It consists of a static HTML page and Javascript file which implements the required behaviour.

Complete the following steps to install and test your OAuth proxy endpoint:

1. Download the files here or review the full gist.
2. Add auth-proxy.html and auth-proxy.js to the same directory on your web server. Your Proxy URL is done!
3. Verify the Proxy URL by visiting the auth-proxy.html page on your server. You should see some text and a link. Make a note of the URL, you will use this URL as Proxy URL when setting up your Developer Accounts and also the OAuth Credentials in CloudSponge.

Next you can set up your OAuth Credentials for each OAuth source, using the URL for auth-proxy.html.

This Javascript implementation page is preferred over our older reference implementations because there are no server-side dependencies. Any site that can host a static HTML page can host the Proxy URL.

Server-side Proxy URL (deprecated)

For new integrations, please use our Javascript Proxy URL. The server-side Proxy URL reference implementations are listed below for reference only.

Your Proxy URL should be a transparent pass-through between the client and api.cloudsponge.com: all request data should be forwarded directly upstream to https://api.cloudsponge.com/auth. Likewise, all response headers and data should be returned directly to the client. The page you create on your site to proxy requests needs to accept all GET parameters, make an HTTP connection to https://api.cloudsponge.com/auth, passing the parameters with the request. When the response comes back from api.cloudsponge.com, the exact headers and body should be returned to the client. The typical gotcha is following redirects: api.cloudsponge.com/auth returns a 302 response in many cases. Ensure that your system is configured to not follow redirects for the proper result.

CloudSponge may return a 302 Found and a Location in the response header. This response header should be returned to the user’s browser. Some platforms will automatically follow redirects so you must ensure that this functionality is turned off on your system.

Important Note: The Proxy URL cannot follow any redirect response from CloudSponge. It must proxy the request and include any GET parameters with the payload to CloudSponge.

We have several reference implementations of working Proxy URLs:

1. HTML/Javascript - Recommended
2. PHP (depends on the CloudSponge PHP library)
3. Ruby (depends on the CloudSponge Ruby gem)
4. ASP .Net
5. Java Servlet
6. Groovy & Grails
7. Python & Django

OAuth Credentials

For your site’s identity to appear on the authentication screens, you will need to register an application at each of the contact sources. Once registered, you will need to add these credentials to your domain’s profile in your CloudSponge account.

Google (Gmail)

After you follow these steps, your users will see your product name in the Google Authentication window.

Important: Google requires you to submit a review of your application before they will allow strangers to use approve your OAuth permission requests. Google warns that the OAuth review may take up to a week. In our experience, the review may be faster than 24 hours as long as Google doesn’t have any questions about your application. We’ve prepared some background and directions to help you navigate the new process successfully. You can still test out your integration immediately.

These are the actions required to set up your Google OAuth:

1. If you haven’t already done so, create a Proxy URL on your application’s domain.
2. Obtain your Google OAuth 2.0 Credentials.
3. Configure your CloudSponge account with your Google OAuth credentials.
4. Request a review on Google’s OAuth Developer Verification Form.

Obtain your Google OAuth 2.0 Credentials

Watch how to create a Google OAuth credential in a few minutes.

Or follow the general steps below:

1. Sign into the Google Developer Console with your Google account.
2. Create a new project, or click on an existing one.
3. Ensure that the Contacts API is enabled for your project.
4. Configure your consent screen with your product name and other details.
5. Create a new credential for your project.
   • Under Application type, select Web application,
   • Fill Authorized redirect URIs with your Proxy URL.
   • Click Create
6. Note your Client ID and Client Secret. You will enter these into CloudSponge.
   • Click over your app credentials in order to view details.
   • Take note of your Client ID, Client secret.

Configure your CloudSponge account with your Google OAuth credentials

1. Sign in to your CloudSponge account and add a new Gmail OAuth Credential.
2. Enter the Client ID, Client secret and Redirect URI values from Google and click on Save button.
3. Open your Account Settings page.
4. Click the OAuth Credentials Settings button for the desired domain:
5. For Gmail, select the newly inserted credential and click on Done button:
6. Test a Google import on your site.

NB If you observe a 400 error with a message of “Error: invalid_scope” when you attempt to complete the OAuth flow, then your OAuth account needs to be reviewed before Google will let you request access to people’s address books. This is a new requirement that they introduced on May 11, 2017. We’ve prepared some background and directions for navigating the new review process.

Request a review on Google’s OAuth Developer Verification Form

Read our background and directions for a quick turnaround from the review process.

Yahoo! (Yahoo! Mail)

After you follow these steps, your users will see your domain in the Yahoo Authentication window instead of ours.

1. If you haven’t already done so, create a Proxy URL on your application’s domain. Your Proxy URL should be set up to proxy all GET requests including the query string to: https://api.cloudsponge.com/auth
2. Sign into the Yahoo Developer Portal with a Yahoo ID.
3. Create a new project to use the Contacts API. This account must have read access to Contacts. Also, we recommend that you set “Read/Write Public and Private” access to Profiles if you intend to use the contact_owner property.
4. Set the Application Domain to your application’s domain.
5. Verify your domain with Yahoo.
6. Record the following values from your Yahoo project: Client ID & Client Secret.
7. Sign in to your CloudSponge account and add a new Yahoo OAuth Credentials.
8. Enter the Consumer Key, Consumer Secret and Application ID that you recorded above and your Proxy URL from step 1 above.
9. Submit and test a Yahoo import.

Microsoft (Outlook.com, Office 365, Exchange Online, MSN, Hotmail, Windows Live)

After you follow these steps, your users will see your domain in the Microsoft’s Authentication window instead of ours.

1. If you haven’t already done so, create a Proxy URL on your application’s domain.
2. Go to My Applications in the Microsoft Registration Portal.
3. Click on Add an app, give it a name and click Create application. You will be redirected to the Appication configuration page.
4. Note the Application Id; it is your Client ID.
5. In Application Secrets click on Generate new password. Note the password; it is your Client Secret.
6. In Plataforms, click on Add Plataform, and select Web.
7. In Redirect URIs, enter the url for the Proxy URL from step 1.
8. In Microsoft Graph Permissions click the “Add” button beside Delegated Permissions. Select Contacts.Read in the modal and click OK. You can remove User.Read as it is not required for CloudSponge.
9. Click Save at the very bottom of the page.
10. Sign in to your CloudSponge account and add a new Outlook.com OAuth Credentials.
11. Enter the Client ID and Client Secret that you recorded above, and the Redirect URI where you created the CloudSponge Proxy in step 1 above.
12. Associate the branding with your site: click Settings, click the OAuth Credentials button beside your site and choose the new branding in the Outlook.com dropdown.
13. Submit and test a Outlook.com import.

You can learn more about Microsoft’s Appication Registration Portal here.

Rebranding Our Applet

By default, your users will see api.cloudsponge.com and “Cloud Copy, Inc.” in the dialog that asks them to give our applet permission to run on their computers.

Replacing our domain name with yours is simple and free. Replacing the digital signature with your company name is a little more complicated and will cost you a little money for a certificate from a third party.

Partial Rebranding

After you follow these steps, our domain name will be replaced with yours but the digital signature will still say “Cloud Copy, Inc.”

1. Download the CloudSponge.com Desktop Applet from https://api.cloudsponge.com/objects/ContactsApplet_signed.jar and store in a public folder on your web server.
2. Modify your response from the /begin_import/desktop_applet endpoint to always return the URL to your signed copy of the Desktop Applet.

Full Rebranding

After you follow these steps, our domain and our digital signature will be removed from the applet.

1. Download and install the Java JDK on your server from http://java.sun.com/javase/downloads/widget/jdk6.jsp.
2. Using ‘keytool’ (supplied with the JDK), obtain a Code Signing Certificate from a certificate authority such as Thawte or Verisign. More information about keytool and jarsigner can be found at http://java.sun.com/javase/6/docs/technotes/tools/index.html#security.
   1. Generate a self-signed certificate using keytool
   2. Generate a CSR using keytool
   3. Send the CSR to the CA
   4. Purchase the certificate
   5. Verify and import the certificate into the keystore generated in #1
3. Download the CloudSponge.com signed applet from https://api.cloudsponge.com/objects/ContactsApplet_signed.jar.
4. Use jarsigner to sign the ContactsApplet.jar with your Code Signing Certificate.
5. Modify your response from the /begin_import/desktop_applet endpoint to always return the URL to your signed copy of the Desktop Applet.
6. Follow @CloudSpongeTech on Twitter. We’ll tweet a notification whenever we issue an update to the applet.

Whenever you update your copy of the applet, you will be required to repeat #3 and #4. The permission request will appear the same as for #2, but the digital signature displayed will correspond to your Code Signing Certificate.