Social

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

social-share-widget

There are two basic methods for customization of a social widget:

  1. 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.
  2. 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

Per-Widget Event Subscription

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”.

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.

Because adding click handlers is common, there’s a shortcut method for adding them. The following is functionally equivalent to the preceding example.

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.

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.

{
“alt_id”: “http://www.facebook.com/profile.php?id=1526228678,
“provider_name”: “facebook”,
“default_photo_url”: “https://graph.facebook.com/1526228678/picture?type=large”,
“email”: “ian.b.taylor@gmail.com”,
“verified_email”: “ian.b.taylor@gmail.com”,
“gender”: “male”,
“preferred_user_name”: “IanTaylor”,
“display_name”: “Ian Taylor”,
“birth_date”: 343954800000,
“first_name”: “Ian”,
“last_name”: “Taylor”,
“city”: null,
“state”: null,
“region”: null,
“postal_code”: null,
“country”: null,
“time_zone”: null,
“connection_count”: 0,
“credentials”: {
“uid”: “1526228678”,
“scopes”: “publish_actions”,
“expires”: “1371994082”,
“accessToken”: “BAAGFJ0KUFpcBABuNMptmYY…”,
“type”: “Facebook”
},
“about_me”: null,
“cur_pos_title”: “Senior Staff Engineer”,
“phone_number”: null,
“company”: “Marketo”,
“cur_pos_start_date”: 1333231200000,
“cur_pos_summary”: null
}