Marketo Social Marketing allows marketers to embed social widgets within websites and landing pages. Social widgets include polls, social share buttons, videos, sweepstakes and promotions like referral offers.
Sample Embedded Share Widget
1 2 3 4 5 6 7 8 9 10 |
<html> <head> <!-- Marketo Widget Loader Script --> <script type="text/javascript" src="//b2c-mlm.marketo.com/jsloader/271d8232-1500-4305-b7ed-05d451b9ee0c/loader.php.js"></script> </head> <body> <!-- The Location of the Social Widget --> <divclass='cf_widgetLoader cf_w_245d8f3c0955454cbd26abc39d0d874c' options='{"outerHeight":400, "outerWidth":600}'></div> </body> </html> |
There are two basic methods for customization of a social widget:
- Using the product’s normal UI and attaching event listeners to be informed when certain actions have happened in the UI to perform additional business logic.
- Replacing the product’s normal UI with a custom one, and activating the popup “stages” of the UI when desired.
Attaching Events to the Normal UI
There are two ways to subscribe to events in the CF JavaScript library, globally, or for a single widget. Events are documented below in the events table.
Global Event Subscription
1 2 3 4 5 6 7 8 9 10 |
<script> cf_scripts.afterload(function(){ CF.events.listen("event_name_here", function(event, arg1){ //Your code to do something on the event goes here. //It will be fired whenever ANY widget fires the event "event_name_here". } ); }); </script> |
Per-Widget Event Subscription
1 2 3 4 5 6 7 8 9 10 |
<script> cf_scripts.afterload(function(){ CF.widget.listen("widget_name_here", "event_name_here", function(event, arg1){ //Your code to do something on the event goes here. //It will be fired whenever the widget named "widget_name_here" fires the event "event_name_here". } ); }); </script> |
An Example
This example shows a previously hidden element with id “signedUp” after a user has completed an offer enrollment for a widget named “referral_SignUp”.
1 2 3 4 5 6 7 8 9 10 |
<div id='signedUp'style='display:none; color:green;'>This is a custom message to let you know that you signed up!</div> <div class='cf_widgetLoader cf_w_referral_SignUp'></div> <script> cf_scripts.afterload(function(){ CF.widget.listen("referral_SignUp", "offer_enrolled", function(){ cf_jq("#signedUp").show(); }); }); </script> |
Basic Events Table
Event name |
Description |
Widgets that use this event |
Supported Arguments (passed to event callback function) |
---|---|---|---|
share_sent | Fires every time a share request is sent to the server for processing | All widgets that have the ability to share | 1.”share_sent” (String) 2. Parameters sent (Object) |
share_success | Fires when the share request is successfully processed. | All widgets that have the ability to share. | 1.”share_success” (String) 2. Share response object, containing message sent and shortened url (Object) |
vote_success | Fires when a user has successfully voted in a poll. | Poll, VS, Vote widgets | 1. “vote_success” (String) 2. Item voted for, including title, description, entity identifier (Object) |
offer_enrolled | Fires when a user has succesfully enrolled in an offer | All offer widgets | 1.”offer_enrolled” (String) 2. Changed user properties (Object), 3. Changed user attributes (Object) |
profile_saved | Fires when a user has updated their profile from profile capture | All non-offer widgets that have profile capture enabled | 1.”profile_saved” (String) 2. Changed user properties (Object) 3. Changed user attributes (Object) |
video_loaded | Fires when an embedded video is fully loaded and initialized. | VideoShare widget | 1. “video_loaded” (String) 2. “.cf_videoshare_wrap” Element that holds the video (jQuery Object) |
Replacing the UI with a Custom UI
To replace the UI with a custom UI, you must first turn off the normal UI, this is done by setting the option popupUIOnly to true.
With this option set, the standard UI will not render on page load, instead the widget will fetch its data and wait for you to start one of its popup stages by calling the CF.widget.activate function and providing options for what it should do.
Here is an example of creating a custom button that launches the referral offer sign up flow for a referral offer widget named referral_SignUp.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<button id="myNewSignUpButton">My newSign Up button</button> <!-- Turn off the defaultreferral offer UI by setting popupUIOnly to true--> <div class="cf_widgetLoader cf_w_referral_SignUp" options="{popupUIOnly:true}"></div> <script> cf_scripts.afterload(function($, CF){ // After the cf script library has loaded, find the button with // id="myNewSignUpButton", and attach a click listener to it. $("#myNewSignUpButton").click(function(){ // When it is clicked, activate the popup widget flow for the referral, // asking it to point to the clicked button. CF.widget.activate("referral_SignUp", {pointTo:$(this)}); }); }); </script> |
Because adding click handlers is common, there’s a shortcut method for adding them. The following is functionally equivalent to the preceding example.
1 2 3 4 5 6 7 8 9 10 |
<button id="myNewSignUpButton">My newSign Up button</button> <div class="cf_widgetLoader cf_w_referral_SignUp" options="{popupUIOnly:true}"></div> <script> cf_scripts.afterload(function($, CF){ // Use the addClickActivate convenience method, which will // automatically make the popup point at the clicked item with id myNewSignUpButton. CF.widget.addClickActivate("#myNewSignUpButton", "referral_SignUp", {}); }); </script> |
Getting Widget UI Data to Put Into Your Replacement UI
If you need data about the widget to draw your replacement UI, you can get the data from the special event ui_data. You can listen for this event with the normal CF.widget.listen function, but doing so can cause a potential race condition where your event listener is added after the widget has already fired theui_data event, thus you never receive data. To avoid this race, use the CF.widget.uiData method instead, which will give you the most recent available ui_data, and listen for all future updates as well. The ui_data event will be fired whenever there is an action taken that would have caused the widget’s standard UI to be redrawn, even if you’ve disabled that ui with popupUIOnly option.
An example that uses uiData function to display the number of entries a user has for a sweepstakes with widget name sweeps_Sweepstakes.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<span>You have <span id="entryCount">?</span> entries.</span> <div class="cf_widgetLoader cf_w_sweeps_Sweepstakes"></div> <button id='myNewSweepsButton'>New Sweeps Up Button!</button> <script> cf_scripts.afterload(function($, CF){ CF.widget.uiData("sweeps_Sweepstakes", function(uiData){ if(uiData.user && uiData.userStatus && uiData.userEntries){ $("entryCount").html(""+ uiData.userEntries); } else{ $("entryCount").html("0"); } }); }); </script> |
Referral Offer SignUp UI Data Reference
Field |
Type |
Description |
---|---|---|
user | Object | The user object of the logged in user. null if no user is logged in |
totalActions | Number | The number of times the sign up offer has progressed past its first stage (share or offer entry depending on other options) |
userActions | Number | The number of times the currently logged in user has performed an action (see above) |
conversionsGoal | Number | The total number of conversions need for a user to earn the offer |
visitsGoal | Number | The total number of referred visits needed for a user to earn the offer |
referralGoal | Number | The total number of referred enrollments needed for a user to earn the offer |
offerRewardLimit | Number | The maximum number of times a user can repeatedly earn the offer |
enrollSuccess | Boolean | true if the user has completed an enrollment in the current page load cycle, false otherwise |
Referral Offer TrackProgress UI Data Reference
Field |
Type |
Description |
---|---|---|
user | Object | The user object of the logged in user. null if no user is logged in |
totalActions | Number | The number of times the track progress offer has progressed past its first stage |
userActions | Number | The number of times the currently logged in user has performed an action (see above) |
conversionsGoal | Number | The total number of conversions need for a user to earn the offer |
visitsGoal | Number | The total number of referred visits needed for a user to earn the offer |
referralGoal | Number | The total number of referred enrollments needed for a user to earn the offer |
offerRewardLimit | Number | The maximum number of times a user can repeatedly earn the offer |
Sweepstakes UI Data Reference (for Social Campaign Sweepstakes, not LM Sweepstakes)
Field |
Type |
Description |
---|---|---|
user | Object | The user object of the logged in user. null if no user is logged in |
startDate | Number (epoch time in ms) | Time the offer becomes active |
endDate | Number (epoch time in ms) | Time the offer ends |
awardLimit | Number | Maximum number of awards that will be given out |
userStatus | String Enum | The status of the user in the current offer |
offerRewardLimit | Number | The number of times a user is allowed to receive an award |
entryMax | Number | The maximum number of entries a user is allowed to have. 0 means unlimited |
entrantCount | Number | The number of users that have enrolled in the offer |
complete | Boolean | true if the offer has completed by progressing over the award limit |
userEntries | Number | Number of entries the logged in user has in the contest |
Social Sign On (Form Fill Widget) Data Reference
Field |
Type |
Description |
|
---|---|---|---|
user | Object | The user object of the logged in user. null if no user is logged in | |
profile | Object | The profile object of all fields returned from provider. See below for an example of this object.
|