Introduction ¶

This document provides guidance on building a Janrain Engage plugin for third-party systems such as CMS, eCommerce platforms, social communities, and so on.

Preparation ¶

Before jumping into the code, the best practice is to make a plan for your plugin. Some items to consider:

• Research developer issues and experiences for the system you are developing in.
• Get a feel for the community standards (for example, expected documentation level, defect tracking, feedback).
• What are the common pitfalls?
• Pay attention to comments about official API documents as opposed to real world experience.
• Select a few popular plugins on the same platform which might potentially interact with your plugin. Test with and without these plugins during development.
• Figure out early how to work with the framework’s administrator interface. Put a lot of work into your UI; make it very idiot-proof, succinct, and provide links.
• Engage offers a special plugin API call (lookup_rp) that delivers all the basic settings your plugin will require to interact with Engage based on the API key. Build your interface with this in mind.
• Watch out for “total conversion” packages (such as, Drupal PressFlow or WordPress BuddyPress) as these can have a drastic effect on your plugin.
• Watch out for CAPTCHA plugins (like, Mollom) that can modify the platform sign-in and signup process and may require special handling for automatic signups with Engage. Usually these plugins are popular and it is important to support them.

Feature Planning ¶

The following list shows popular features to include. The list starts out with the essentials, and continues down to the ‘nice-to-have’ items.

Note: We discuss localization in its own section, but you should probably address it during each step.

• Implement Sign-in widget — Enable an existing user link to the provider by the Engage identifier. Typically offered on the user profile page. You can either store the Engage ID on the user record, or metadata, or in a new table depending on the standards for this environment. Other features to consider include changing your provider, adding or dropping providers, or the ability to place the widget elsewhere.
• Registration of new accounts — Allow a visitor to create a user purely from the Janrain Engage data. Ideally, the administrator should be able to enable and disable this feature. The user should not be required to register using their Identity Provider, but Janrain research shows that it is a good way to get users to register that would not typically register.
• Collection and storage of profile data — Janrain Engage provides a wealth of user data. The questions to ask when capturing the data is how to integrate it into the user database. The amount and quality of the data also varies by provider. Another option is to add a feature that stores the raw data returned from authentication for later processing.
• Social sharing — Janrain Engage allows several types of social sharing, but the most common integration is to share a user’s comment on an activity.  Possible features to include are sharing links with comments, creating a pop-up window to create a comment, sharing of posts and articles, sharing of links to post and articles, adding a check box to enable the author to share the creation of a post or article, or adding an administrator interface to control these features.
• Modularization or API for your plugin — Provide an API that allows other developers access to some variables to enable interaction with templates. It is also useful to provide hooks during registration or sign-in, to enable other plugins to trigger related events. Consider offering a formal API to allow other plugins to depend on yours.
• Localization — Provide an interface for administrators to customize text, or develop a localization framework to provide pre-defined changes. These could pre-fill a form based on selections from a menu.
• User-facing messages — Provide an interface for the administrator to customize the user-facing messages generated by your plugin.

The Engage Plugin API Call ¶

Engage provides an API call, lookup_rp, that handles commonly-used variables as well as data used by plugins. Using this call helps to future-proof plugins because any changes to the broader API will be automatically updated in lookup_rp, eliminating the need to update other code.

For more information, refer to the lookup_rp API entry.