Introduction
V3's JavaScript SDK provides access to a rich set of client-side functionality for your website, and it is required if you want to enable V3's EngageAnywhere technology (widgets and APIs).
Table of Contents
Setting Up the JavaScript SDK
We recommend adding V3's JavaScript SDK to every page on your website. There are two easy steps:
-
Insert a single <script> tag into the header of EACH page
Copy and paste the following element into the <head> tag of your HTML. Replace "[YOUR_CLIENT_ID]" with the ID you were given during setup. For example, if your organization is named Arcticause and your V3 Platform is located at http://arcticause.mobilizationlabs.com, then arcticause is your client ID.<script src="http://[YOUR_CLIENT_ID].mobilizationlabs.com/api/3.0/mlabs-service.js"></script> -
Insert a xmlns attribute into the <html> tags
In order for Internet Explorer to correctly render V3 and Facebook widgets, you must specify a "wf" and "fb" namespace in your page's html element. To do so, make sure to include the following in your head element:<html xmlns="http://www.w3.org/1999/xhtml" xmlns:wf="http://www.mobilizationlabs.com" xmlns:fb="http://facebook.com">
Once you've added the JavaScript SDK, your web pages will have full access to all V3's widgets, client-side APIs, and supporter identity methods.
Note: The xmlns:fb="http://facebook.com" attribute above is needed if you want Facebook funtionality to work properly on your site.
Using the Javascript SDK
V3's Javascript SDK opens up a number of possibilites. The following features are automatically enabled and ready for you to use:
JavaScript API Wrapper
A JavaScript API Wrapper comes bundled with your SDK, giving you direct access to many of V3's REST APIs.
WFML Widgets
V3 comes with a powerful collection of V3ML Widgets that you drop into your website with simple HTML tags. The JavaScript SDK then turns these HTML tags into fully functional web apps that your supporters interact with.
Supporter Identity Framework
V3 is your complete signup and login system, integrating directly into Facebook's Open Graph and other 3rd-party services. With this single authentication environment, V3 tracks which supporters are doing actions, passing-along actions, and recruiting their friends, then channels this data into powerful measurement tools from within your staff app.
V3's Javascript API Methods provide easy access to your visitors' login status and profile data:
|
Returns true if the visitor is logged in or false otherwise.
|
|
|
Returns the current supporter's profile data.
|
Global Event Handling
V3 Platform provides both JavaScript and CSS event triggers that you can use to display dynamic content and user interaction on your website.
JavaScript Event Triggers:
Use the globalEvent() handler to bind custom JavaScript functions to particular events that occur within V3:
V3.globalEvent('[EVENT NAME]', [YOUR CUSTOM FUNCTION])
V3 currently supporters three global events.
|
Event Name
|
Description
|
| initialized | The initialized event fires when the JavaScript SDK has finished loading. You can now modify the DOM and markup created by V3ML widgets. |
| login | The login event fires when the user logs in after the page has been loaded. This allows you to update the page to reflect the new logged in state, and you can now access the current user using V3.getSupporter(). |
| logout | The logout event fires when the user logs out after the page has been loaded. This allows you to update the page to reflect the new logged out state. |
For example, the following code displays an alert() with the visitor's first name (if we know it) when the user logs in...
V3.globalEvent('initialized', function() {
// do something with V3
});
Note: In addition to global events, V3 also supports widget-specific events that can be called with V3.widgetEvent().
CSS Event Triggers:
Use simple CSS classes to show and hide DOM elements:
|
Class Name
|
Description
|
| .WF-show-if-known | Any HTML tag with this CSS class will be shown if the visitor IS a recognized supporter, otherwise it will be hidden. |
| .WF-show-if-unknown | Any HTML tag with this CSS class will be shown if the visitor is NOT a recognized supporter, otherwise it will be hidden. |
For example, the following tag is displayed only if the current visitor is a known supporter. To avoid displaying the wrong HTML tag momentarily while your page loads, you should hide it using css or inline style.
<div class="V3-show-if-known"> This will be displayed only if we know the visitor.</div>
Explore More: V3's ML widgets include additional event handlers that you can use in your webpages.