Page History

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
SEO Metadata

This method displays the Share Bar plugin, which consists of one or more share buttons arranged in a horizontal or vertical bar.

Description

This method displays the Share Bar plugin, which consists of one or more share buttons arranged in a horizontal or vertical bar. The buttons can be direct bookmark buttons, a general share button, or an email button. Certain bookmark buttons including the general share button can display a counter representing the number of shares. For more information regarding counters, refer to the socialize.getProviderShareCounts API method.

Once a user clicks a direct bookmark button, the window of the provider will be opened for direct bookmarking. Once a user clicks the general share button, the Simple Share mode of the Share plugin will pop up, enabling your user to share and bookmark content and site activities to a selected social destinations.

Panel
borderColor#81C0FC
bgColor#F4F7FC
borderWidth1
borderStylesolid

Notes:

  • If you plan on integrating the Share Bar plugin, we highly recommend reading the Share Bar plugin page in the Developer's Guide, which is a step-by-step guide for integrating the Share Bar plugin and also provides a reference and guide for the various customization options.
  • Full control over content shared to Facebook requires implementation of Open Graph meta tags in your website. Meta tags are supported by all major social networks. Meta tags can be tested and configured using the Facebook debugger and Google's webmaster tools. For more information see Sharing Content.   

 

 

Include Page
Template_gigya api header syntax
Template_gigya api header syntax

Include Page
Template_gs api header params
Template_gs api header params

RequiredNameTypeDescription
Yes

shareButtonsstring or an array of objects

An array of ShareButton objects or a string containing a comma-separated list of providers, representing the buttons to display in the share bar. When passing a comma-separated list, the plugin behaves as if an array of ShareButton objects was passed, where the only value in each object is the provider name.

Valid provider names include:

  • facebook
  • twitter
  • linkedIn
  • microsoft
  • whatsApp 
  • reddit
  • googleplus
  • googlebookmarks
  • vkontakte
  • spiceworks
  • viadeo
  • nkpl
  • xing
  • tuenti
  • pinterest*
  • kindle
  • baidu
  • friendfeed
  • tumblr
  • stumbleupon
  • qq
  • sina
  • mixi* *
  • wanelo
  • share

(Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used). 

In addition to the provider names listed above, the comma-separated string containing the provider list may also include these reserved names, that implement the provider's own (native) button:

  • 'facebook-like' - represents the Facebook Like button. 
  • 'facebook-share' - represents the Facebook Share button. Items shared via the 'facebook-share' button do not appear in reports. 
  • 'facebook-send' - represents the Facebook Send button.
  • 'facebook-subscribe' - represents the  Facebook Subscribe button. This button can only be configured as a full ShareButton object, not by a simple string.
  • 'twitter-tweet' - represents the Twitter Tweet button.
  • 'twitter-hashtag' - represents the Twitter Hashtag button. Specifies a hashtag within the text and the button.
  • 'twitter-mention' - represents the Twitter Tweet to button. Allows you to specify a user to mention from within the text and the button.
  • 'google-plusone' - represents the Google +1 button.
  • 'googleplus-share' - represents the Google + Share button.
  • 'googleplus-interactive' - represents the Google + Interactive Post button.
  • 'moshare-sms' - represents the moShare button for mobile sharing via text message. moShare cannot be used over https.
  • 'foursquare' - represents the foursquare button.
  • 'foursquare-save' - represents the Save to foursquare button.
  • 'share' - represents a button in the share bar that triggers the Simple Share dialog.
  • 'email' - represents a button in the share bar that triggers the standard share dialog in email mode.
  • 'comments' - represents a Comments button. The button is displayed with a counter when the ShareButton object of the comments button contains the fields: categoryID and streamID, and the number of comments is larger than 0. When using the Comments plugin on the same page, use the onShareButtonClicked event to direct the user to the Comments box. See example below.
  • 'print' - represents a button in the share bar that triggers the print operation.
  • 'pinterest-pinit' - represents the Pinterest pin-it GD* button.
  • 'tvtag' - represents the TVTag button (formerly the GetGlue button).
  • 'lineit' - represents the LINE button. This button can be used in mobile only.
  • 'hatena-bookmark' - represents the Hatena bookmark button.

*** The Googleplus button is unable to display share counts because Google does not have an API that returns share counts.
**** The Pinterest pin-it button requires you to define a thumbnail URL in the
userAction object, otherwise it won't work. 

Anchor
Hetena
* The 'hatena-bookmark' button text is in Japanese by default. To change it to English, add param " lang: 'en' " explicitly to Hatena's 'ShareButton Object'.

Yes
containerIDstringAn ID of a <div> element on the page in which you want to display the plugin.
Yes
userActionUserAction objectThe user action to share. The UserAction object enfolds newsfeed data, including text, media, link, etc., and is used to construct the newsfeed item for all networks except Facebook, Twitter and Google, which use Open Graph (OG) tags instead. For more information on using OG tags, see Sharing Content.
Notes:
  • A shared URL must match the approved URLs (domains) for the specified API key, otherwise the share will not work.
    Include Page
    Share URL Restrictions Template
    Share URL Restrictions Template
     
  • When Twitter is the provider, only the Title and Link Back are posted.
No
actionAttributesJSON objectIn Gamification your users receive points for actions they perform on your site, in this case clicking a share button grants the user points. Action Attributes may be used to annotate actions with additional information, such as the section of the website that generated the action. If you set here the actionAttributes, each time a user clicks a share button, the action also receives an attribute, for example "tv-show":"glee", which can mean that the action was performed on the "Glee" page of the site. 
Include Page
Template_gs api actionAttributes description
Template_gs api actionAttributes description
No
buttonImagesJSON objectUsing this object you may override the default design of a share button. Specify your alternative button images using the object fields. The following fields are supported:
  • buttonLeftImgUp
  • buttonLeftImgOver
  • buttonCenterBGImgUp
  • buttonCenterBGImgOver
  • buttonRightImgUp
  • buttonRightImgOver
  • countBGImg.

Read more in the Applying a New Button Design guide.

Panel
borderColor#81C0FC
bgColor#F4F7FC
borderWidth1
borderStylesolid

Notes:

  • The images are specified separately from the buttonTemplate in order to be pre-loaded. If pre-loading is not required the images may also be specified directly in the buttonTemplate.
  • Custom design can only be applied to generic and non-native buttons. Styling parameters applied to Social network native buttons take no effect. A list of native buttons can be found in the description of the 'shareButtons' parameter above.
No
buttonTemplatestring
(HTML)
This parameter enables you to override the default design of the buttons in the Share Bar that do not include a counter, such as the "Print" and "Email" buttons. The parameter defines an HTML template representing the appearance of each button. The HTML template supports the placeholders $iconImg, $text, $onClick. See Using Button Templates for information and examples.
No
buttonWithCountTemplatestring (HTML)This parameter enables you to override the default design of the buttons in the Share Bar that include a counter, such as the general "Share" button. The parameter defines an HTML template representing the appearance of each button. The HTML template supports the following placeholders: $iconImg, $text, $onClick, $count. See Using Button Templates for information and examples.
No
cidstring
Include Page
Template_gs api cid description
Template_gs api cid description

Include Page
Template_gs override params short note
Template_gs override params short note
No
contextobjectA reference to a developer created object that will be passed back unchanged to the event handlers as one of the fields of the eventObj (see extended explanation in the "Plugin Events" section below).
No
countURLURLAllows to specify a canonical URL and counts are then retrieved from this URL. The countURL ensures that the counts are incremented properly, and tracks counts against the canonical URL. To count Facebook's native buttons you must Enable Native SDK Capabilities (see the shareButtons parameter for native button details). Other native buttons will not be counted.
No
deviceTypestringDetermines the type of the device on which the Share Bar UI is displayed. The parameter supports the following values:
  • desktop  (default) - render the share bar in regular mode
  • mobile  - render the share bar in mobile view mode 
  • auto  - identify the device (user-agent) and if it is a mobile device, render in the mobile view mode

When the Share Bar is set to deviceType mobile or auto (on mobile), clicking the email share will open the mail client rather than the Gigya share bar UI.

No
displayCountThresholdintegerThe threshold of the counter to be displayed, i.e. each button in the share bar will display its counter only once it reaches this number. If the counter has not reached this threshold, the counter will not be displayed for the provider. The default value is 0.
This parameter does not apply to the Facebook Like/Send and Twitter buttons.
No
facebookDialogTypestringApplicable only for sharing through Facebook. This parameter determines which Facebook dialog will appear when clicking the share button. Options are:
  • 'share' (default value)
  • 'feed'

When using the 'share' dialog, it is required to implement open graph tags on your page, since Facebook's 'share' as well as other major social networks, use open graph tags to get the news feed item data for the shared item, rather than using data from the 'user action object'. 

No
grayedOutScreenOpacityinteger
(0-100)
This parameter allows you to gray-out the screen behind the plugin to emphasize the "modal" environment in Multiple Selection Share mode. Graying-out covers the entire page behind the plugin with a gray transparent layer. Using this parameter you can define the opacity of the gray layer. The value of this parameter should be a number between 0-100, where:
  • 0 - clear (not grayed out). This is the default, if this parameter is not set.
  • 100 - opaque (blacked out).
  • 20 - is our recommended value for gray-out opacity.
No
iconsOnlyBooleanThis parameter determines whether the share bar buttons are displayed as icons only, without text and borders. The default value of this parameter is 'false'.
No
initialViewstringDetermines the initial view of the plugin when it loads in Multiple Selection Share mode. There are three options:
  • 'share' (default) - shows the default share view.
  • 'more' - shows the "More" view. This option is only relevant if the showMoreButton parameter (see below) is set to 'true'. To learn more, please read the Adding More Destinations page.
  • 'email' - shows the "Email" view. This option is only relevant if the showEmailButton parameter (see below) is set to 'true'. To learn more, please read the Sharing via Email page.
No
KeystringUsing this parameter, you can specify all the API keys of the social networks that require an API key, e.g. 'mixiKey'.
No
layoutstringSets the arrangement of buttons in the bar. May be:
  • 'horizontal' (default)
  • 'vertical'
No
noButtonBordersBooleanThis parameter determines whether the share bar buttons are displayed without borders. The default value of this parameter is 'false' (the buttons are displayed with borders). This parameter is only applicable if iconsOnly is false.
No
shareCountCacheTimeoutintegerThis parameter defines how long the share counts data will be stored in local cache. The default value of this parameter is 300,000 milliseconds. The share counts data will not be refreshed within this interval, for better performance.
No
shareTimeoutintegerSets a timeout to the sharing operation in Multiple Selection Share mode. Set this parameter with the maximum number of seconds to wait for the sharing operation to be completed. If a timeout occurs, the Share plugin will close and an onError event will be fired with errorCode=504001 and errorMessage="Share request timeout".
No
shortURLsstring
Include Page
Template_gs api shortURLs description
Template_gs api shortURLs description

Include Page
Template_gs override params short note
Template_gs override params short note
No
showCountsstringThis parameter determines if and where to display the share counts in relation to the share button. The options are:
  • 'right' (default)
  • 'top'
  • 'none'

The following providers support counters: 'facebook' , 'stumbleupon', 'linkedin', 'vkontakte', 'facebook-like',  'facebook-share', 'facebook-send', 'twitter-tweet', 'google-plusone', 'moshare-sms', 'share', 'comments', 'pinterest', 'pinterest-pinit', 'hatena-bookmark'. Note: for provider='moshare-sms'  the counters can be either right or none, if top is defined, the moshare button will not display counters. 

Shares posted using the generic +Share button will not be counted as shares made by the other buttons.

In addition, showCounts will only work when the shareButtons parameter (see above) is a string.

No
showTooltipsBooleanThis parameter's default value is 'false'. If set to 'true', a tooltip will be displayed when the mouse hovers over a social network icon. The tooltip presents the social network's full name. This parameter is relevant only in Multiple Selection Share mode.
No
tagsstringA comma separated list of tags that are used to identify the share operation.
No
<socialNetworkName>UserActionUserAction objectIt is possible to specify different content to publish for each social network in Multiple Selection Share mode. For this purpose, the method supports a set of parameters with the same name format: (i.e., facebook, twitter, googleplus, etc.) followed by "UserAction". For example: twitterUserAction - specifies the content to be used specifically when publishing to Twitter.
Each of these optional parameters accepts a UserAction object and if specified override the userAction parameter when posting to that provider. In other words, the userAction parameter (see above) specifies the default content to be used for all social networks and UserAction specifies the content to be used for the specific network.
No
userMessagePlaceholderstringText that appears as a placeholder for the user message in the shareUI when in multiselect mode. When the user clicks the user message input box in the shareUI, the text disappears.
No
wrapBooleanIndicates whether to "wrap" the buttons in the Share Bar plugin. The default is 'false', and when set to 'true' the share bar's buttons will be automatically wrapped to the next line if the current line isn't wide enough to display all the buttons.  
Deprecated: 
Deprec
facebookLikeButtonJSON object Deprecated . Please use the shareButtons parameter instead, along with the 'facebook-like' value.
This parameter adds the Facebook Like button to the share bar.

Include Page
Share Additional Common Parameters Template
Share Additional Common Parameters Template

Include Page
Template_gs api common component events
Template_gs api common component events
 

onSendDone Event Data

FieldTypeDescription
Include Page
Template_gs api common event obj fields
Template_gs api common event obj fields
providersstringThe name of the sharing target (e.g., 'twitter', 'email'). Pinterest does not fire this event.
userMessagestringThe textual message that the user entered in the editable text box of the Share Plugin.
targetURLstringThe URL that was shared.

  

onSendDone Event Data - Email

When a user chooses to share via email, he will use the plugin's email screen and press the 'Send' button. In this situation, Gigya fires an onSendDone event with the providers field set to 'email' and with extra email related fields.

FieldTypeDescription
Include Page
Template_gs api common event obj fields
Template_gs api common event obj fields
providersstring'email'.
userMessagestringThe user custom message.
recipientsarrayAn array of objects that each has a name property and an email property corresponding to the recipients of the email that has been sent.
senderstringThe name or email of the sender.

To learn more about using this event, please read Sharing via Email.

onShareButtonClicked Event Data

FieldTypeDescription
Include Page
Template_gs api common event obj fields
Template_gs api common event obj fields
shareItemShareButton objectThe object representing the share button that has been clicked. Note: Pinterest does not fire this event.

 

Global Event Triggered

By using this Plugin, the following global event may be triggered: onConnectionAdded .

To register an event handler use the socialize.addEventHandlers API method. Refer to the onConnectionAdded event data. Refer to Events to learn more about how to handle events generated by the Gigya service.

Code Sample

Code Block
languagejs
linenumberstrue
var ua = new gigya.socialize.UserAction(); 
ua.setLinkBack("http://www.youtube.com/watch?v=jqxENMKaeCU"); 
ua.setTitle("Adobe Gets Into Widget Distribution And Advertising With Help From Gigya");

var params = { 
    userAction:ua,
    shareButtons: "facebook-like,google-plusone,share,twitter-tweet,email",
    containerID: 'divButtons' // The ID of the <DIV> element on the page in which the plugin is displayed
};

// Show the share bar
gigya.socialize.showShareBarUI(params);

Include Page
Template_gs api example footer2
Template_gs api example footer2

Anchor
Sample-commentsProvidershowCommentsUI
Code Sample (using the comments provider with showCommentsUI)

When using the Share Bar Comments provider in conjunction with the Comments plugin (comments.showCommentsUI), you need to capture the Comments button click event in order to send the user to the Comments box on the page. This can be done as follows:

Code Block
languagejs
linenumberstrue
<script type="text/javascript">
    function chkButton(btn) {
            if (btn.shareItem.provider == 'comments') {
                var comDiv = document.getElementById('commentsDiv');
                comDiv.scrollIntoView(false);
                }
            }

var ua = new gigya.socialize.UserAction();
ua.setLinkBack("http://www.youtube.com/watch?v=jqxENMKaeCU");
ua.setTitle("Adobe Gets Into Widget Distribution And Advertising With Help From Gigya");

var shareBarParams = {
    userAction:ua,
    shareButtons:
    [
            { // General Share Button
                provider:'share',
                tooltip:'General Share Button',
                userMessage:'default user message'
            },
            ......
            { // Comments button
                provider: 'comments',
                categoryID: 'happyComments',
                streamID: '123',
             }
        ],
        containerID: 'divButtons', // location of the Share Bar plugin
        operationMode: 'multiSelect',
        onShareButtonClicked: chkButton
	};

// Show the share bar
gigya.socialize.showShareBarUI(shareBarParams);

Include Page
Template_gs api example footer2
Template_gs api example footer2

Include Page
Enable Retrieving User Contacts Notice Template For Share
Enable Retrieving User Contacts Notice Template For Share

In the ShareBar Plugin demo you will find a complete working example, which uses the socialize.showShareBarUI method. You may view the code, run it and view the outcome.

Include Page
LSSDK JS
LSSDK JS

HTML
<script>
$(document).ready(function() {
    lssdk.tableFixer();
});
</script>