Anyone can use the easy-embed Clef application creation iframe to allow users of their plugin to quickly create a Clef application for their site without leaving the plugin environment.

Embeding the iframe

When you embed the iframe, you must provide a variety of variables, which allow Clef to customize the experience for the user. Each of these variables must be passed as a URL parameter with a URL encoded value.

domain — The domain that the website is hosted on. In WordPress, we get this value by accessing urlencode(get_option('site_url')).
name - The name of the application that will be created. In WordPress we get this value by accessing urlencode(get_option('blogname')).
source — A source ID that you've agreed on with the Clef team. For WordPress, this is just wordpress. For Joomla, this will be joomla. For Magento, this will be magento. This allows the iframe to do the requisite customizing for the platform.
affiliate_id - A unique ID given to you by the Clef team that allows you to get affiliate revenue from future paid-plan signups by users that create Clef applications through your plugin.

The iframe is optimized to be displayed with a width of 525px and a height of 350px, but it should expand or shrink as necessary to acommodate your layout.

Here is an example iframe embed tag:

<iframe 
  src="https://clef.io/iframes/application/create?domain=SUGGESTED_SITE_DOMAIN&name=SUGGESTED_SITE_NAME&source=wordpress&affiliate_id=12345" 
  width="525" 
  height="350">
</iframe>

Listening for the completed event

When the user successfully creates an application, the iframe emits an event, which allows you to auto fill the necessary settings form fields in your plugin. You could have your user manually copy and paste the Clef application ID and Secret, but listening to this event and autofilling the fields is the preferred user experience.

To listen to this event, auto fill the form fields, and auto submit the form, add the following snippet of Javascript to the page with the iframe with the correct variables.

NEW: In addition to the App ID and App Secret, this event will provide an Oauth code for the user who just set up the application. This OAuth code should be exchanged for the clef_id of the user through the standard handshake process, so that the user can be autoconnected on application connection. As an example of this, you can see the Clef for WordPress plugin take this OAuth code and submit it as part of the form, then on the backend, exchange this OAuth code for the user_id and associate the user with their Clef account.

(function($) {
  widow.addEventListener('message', function() {
    if (!(/https:\/\/clef.io/.test(data.origin))){
      return;
    }
    var appID = data.data.appID,
      appSecret = data.data.appSecret,
      oauthCode = data.data.oauthCode,
      // the form field where the user would normally fill 
      // in their Clef application ID
      appIDFormFieldSelector = "FILL_THIS_IN",
      // the form field where the user would normally fill 
      // in their Clef application Secret
      appSecretFormFieldSelector = "FILL_THIS_IN",
      // the form field where the OAuth code for the user
      // will be submitted
      appSecretFormFieldSelector = "FILL_THIS_IN",
      // the submit button on the form where the
      // user fills in their Clef application ID and Secret
      submitFormSelector = "FILL_THIS_IN";

    $(appIDFormFieldSelector).val(appID);
    $(appSecretFormFieldSelector).val(appSecret);
    $(oauthCodeFormFieldSelector).val(oauthCode);
    
    $(submitFormSelector).trigger('click');
  });
{).call(this, jQuery);

Example implementation

For an example implementation, please see the Clef WordPress plugin. You can find the iframe embed URL here and the javascript include here. The implementation may vary a little because it was created before we generalized the use of this tool.

Help

If you have any problems with setting this up, please email support@getclef.com or join our public chat room here.

jessepollak/clef_application_iframe_guide.md

Select an option