Developer Documentation

Replacing CloudSponge Branding

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.com.

CloudSponge offers you the ability personalize the user experience with your own domain so that your users never see our brand name anywhere.

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

  1. Set up a Proxy URL on your domain
  2. Create a developer account with Google and Yahoo!
  3. Configure CloudSponge to use your Google/Yahoo developer credentials (Consumer Credentials)

The import applet can also be rebranded, although the process is slightly more involed becuase it requires you to obtain a code-signing certificate. Read more in the section below.

Rebranding Gmail and Yahoo Imports

The Proxy URL

The delegated authentication techniques provided by Gmail and Yahoo 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 token 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 or Yahoo) and proxy that to CloudSponge.

The page you create on your site to proxy requests needs to accept all GET and POST parameters, make an HTTP connection to https://api.cloudsponge.com/auth, passing the parameters with the request and finally return the literal response. In effect, your Proxy URL is makes it appear to https://api.cloudsponge.com/auth as though our page received the original request.

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 the redirect to CloudSponge, it must proxy the request and include any GET and POST parameters with the payload to CloudSponge.

We have several reference implementations of working Proxy URLs:

  1. PHP (depends on the Cloudsponge PHP library)
  2. Ruby (depends on the Cloudsponge Ruby gem)
  3. ASP .Net
  4. Groovy & Grails
  5. Python & Django

Consumer 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 domain in the Google 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 and POST requests (including the query string and form parameters) to: https://api.cloudsponge.com/auth
  2. Sign into Google and create a new domain via the manage domains page.
  3. Go through Google's domain verification process.
  4. In Google's domain interface, enter your domain your user's will see as the 'Target URL path prefix' and save the page.
  5. Optional: Register your web application with Google. This improves the messaging on the Google Access Consent page.
  6. Record the following values: OAuth Consumer Key & OAuth Consumer Secret
  7. Sign in to your CloudSponge account and add a new Gmail Consumer Credential.
  8. Enter the OAuth Consumer Key and OAuth Consumer Secret that you recorded above and your Proxy URL from step 1 above.
  9. Submit and test a Google import.

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 and POST 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 both Yahoo Mail and Yahoo Contacts.
  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: API Key (Consumer Key), Shared Secret & Application ID
  7. Sign in to your CloudSponge account and add a new Yahoo Consumer Credential.
  8. Enter the API Key, Shared Secret and Application ID that you recorded above and your Proxy URL from step 1 above.
  9. Submit and test a Yahoo import.

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.

Branding-applet

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 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 endpoint to always return the URL to your signed copy of the Desktop Applet.
  6. Send an email to support@cloudsponge.com letting us know that you are hosting your own applet. We'll send you 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.