BYOK CloudSponge Integration

Welcome platform provider! This document describes how to set up your platform to integrate the CloudSponge Contact Picker in a way that lets your customers use their own CloudSponge account for billing purposes. We call it BYOK for Bring Your Own (CloudSponge) Key.

Why BYOK?

CloudSponge tracks and bills according to usage of our product with a given key. When your customers use our Contact Picker on your platform, the usage will be associated with the key that we see on our side, so in order to separate your platform’s account and usage from your customers, they need to be able to use their own CloudSponge key on your platform.

You are reading this document because you want your customers to be able to add their own CloudSponge contact picker to your platform. This document explains how. In it, we cover:

• How you can direct your customers to CloudSponge to get their key.
• How to render the Contact Picker script and options.
• How to ensure that your customers are able to use your OAuth credentials.

Hang on!

Before you proceed, make sure that you have your PARTNER_CODE. You’ll need to use it at several points of integration to be sure that CloudSponge can identify your platform and properly associate your customers within our system. If you don’t have your PARTNER_CODE, contact us and we’ll help you find yours.

After following our usual installation, all the Contact Picker usage will be associated with the CloudSponge account belonging to your platform. Billing is tied to usage, so any customers using CloudSponge in this manner will be added to your CloudSponge bill.

1. Let your customers use their CloudSponge key

So in order to separate the usage and billing, you’ll need to let customers enter their own CloudSponge key. There are two changes required on your side to support this:

• Our customers need to be able to input their CloudSponge key in your platform.
• Your platform must use this CloudSponge key when rendering the widget script, i.e. https://api.cloudsponge.com/widget/#{key}.js

This lets customers use their own CloudSponge contact picker within your platform, but there are still two missing requirements:

• Attribution – we want to track which customers you have enabled to use our service, and
• OAuth – since your platform is the data controller for the end-users’ contacts, we think it’s reasonable that your customers don’t have to all set up and configure their own Google OAuth in CloudSponge.

2. Make sure your customers are associated in CloudSponge

Both of these requirements are supported by associating your platform and the customer’s account in the CloudSponge system. We have two places where we make sure that this association is created. To support these there are two additional changes you’ll need to make:

• When you send customers to CloudSponge, use a URL with a special parameter that tells us that they came from your app:
  https://app.cloudsponge.com/v3/app/signup?utm_source=PARTNER_CODE&utm_campaign=partner&utm_medium=website
  Alternatively, you can use any page on our marketing site and include the utm parameters, such as:
  https://www.cloudsponge.com/?utm_source=PARTNER_CODE&utm_campaign=partner&utm_medium=website
• When you render the widget on the page for any customer, include an additional option in the initialization code:

  cloudsponge.init({
    //... other options
    referrer: 'PARTNER_CODE'
  });

It’s possible that customers may already have their own CloudSponge key. There’s no need for them to create a new CloudSponge account. The second change (adding the referrer option to your widget initialization code) will ensure that any widget key that is being used on your platform has the correct association.

When you have completed these steps, let us know and we’ll work together to verify them.