Share

Skip to end of metadata
Go to start of metadata

 

Introduction

The Share add-on makes sharing intuitive by prompting users to share after they take action (leaving a comment, or purchasing an item) on your site. This dynamic way of sharing can significantly increase traffic through word-of-mouth by allowing users to publish their site actions to social networks. The Share add-on helps streamline the process of sharing with friends in social networks and acts as a sharing console, enabling the user to choose to which networks to share.

You can use the Share Wizard to customize the visual aspects of the Share add-on design, view, and grab the customized code.

How it Works

After a user performs a share-worthy action in your site (for example, submits a comment) a share pop-up dialog is presented, encouraging the user to post his action to social networks. The user is given an option to choose to which social networks he want to post the content, edit his personal message, and get a sneak preview of the feed item his social network friends will see.
 


When the user presses the "Publish" button, Gigya publishes the feed item to each of the social networks that the user selected (on the left hand side of the add-on).

 

What's in this Guide?

This document will guide you on how to publish user actions to the various social networks. For convenience, we have divided this document into levels of complexity:

  • Quick Start Implementation - learn how to quickly integrate the Share add-on, and publish feed items to the various social networks.
  • Simple Share - learn about the Simple share operation mode of the Share add-on, which allows users to publish feed stories without having to be connected to the site.

  • Advanced Sharing - learn how to implement the full richness of news-feed sharing, including adding various media items (Images/ a Flash file/ an Mp3 file/ a Video). The Advanced page goes deeper into the subject, and elaborates on all the customization options available.

For example, a newsfeed including video (and more) published on Facebook:

  • The 'More Networks' Screen - Learn how to add numerous additional destinations for social sharing. The additional destination are provided through the "More" button on the Share add-on. When the user clicks the "More" button, the Share add-on presents a choice of destination icons for posting.
  • Sharing via Email - Learn how to add an "Email" button to the Share add-on and enable sharing feed items via email.
  • Automatic Sharing - Learn how to activate an automatic sharing on an action in your site without prompting the user with the Share add-on.

 

Quick Start Implementation

Before you begin: Make sure that you have already set up social network application settings before you continue. For more information on how to set up an external application for use with your Gigya account, see the Setting Up External Applications in Social Networks documentation and select a specific network.

Important Note: If you intend to use socialize.showShareUI or socialize.showShareBarUI, it is required to check the Enable retrieving user contacts permission of the General Permissions page of the Gigya Console.

Implementation Overview

If you already have included Gigya social login in your site, adding Share should be simple, and involves only adding a few lines of code:

  • Construct a UserAction object, which represents an action taken by a user on your site. The basic elements you need to include in the object are:
    • Title - The title of the posted content.
    • Link Back - A link that typically points to the content source.

      When sharing URLs via any Gigya Add-ons, the URL being shared must be a publicly accessible URI. If the URI is behind a firewall, an HTTP Auth, or does not respond within 5 seconds of a request to retrieve the URL of the page, even if the URL is within a whitelisted domain, Gigya will respond with errorCode 400120 - Invalid Site Domain, and the share will fail.

       
    • Description (optional) - A description of the story or item.
    • Media Item/s (optional) - This can be image/s, a Flash file (inc. video players), or an Mp3 file.
 
Note: It is highly recommended to implement Open Graph Tags directly on your HTML, for better structured news feed post on Facebook ('like'), Twitter and Google (+1).
This way native sharing when copy-pasting your site URL will structure the share post as defined.

 

 

  • Call the showShareUI API to activate the Share add-on and enable the user to share his action.

Code Example

Add the following code snip to activate the Share add-on that is presented in the screenshot above:

// Constructing a UserAction Object
var act = new gigya.socialize.UserAction();

// Setting the Title
act.setTitle("This is my title");

// Adding a Link Back
act.setLinkBack("http://www.gigya.com/site/content/socialize.aspx");

// Setting the Description
act.setDescription("This is my Description");

// Adding a Media (image)
act.addMediaItem( { 
    type: 'image',      // Type of the media (image/flash/mp3)
    src: 'http://graphics8.nytimes.com/images/2006/01/02/science/03cute.large2.jpg',   // URL to the image source
    href: 'http://www.gigya.com/site/content/socialize.aspx'    // URL to redirect the user when he clicks the image
 });

// Activate the Share add-on
gigya.socialize.showShareUI({  userAction:act });

 

Code Explanation

Step 1: Construct a UserAction Object

The UserAction object represents a User Action. The first step you must take in order to publish a User Action is to construct a new UserAction object. We use the UserAction object constructor for this purpose:

var act = new gigya.socialize.UserAction();  

Step 2: Fill the UserAction Object with Data

After you have constructed the object, you can use the various UserAction member methods to set the object's properties. For example:

act.setTitle("This is my title");
...

The UserAction's object properties represent the various items of which a User Action may consist: User Message, Title, etc.

Step 3: Invoke the Share add-on

Call the showShareUI API method:

gigya.socialize.showShareUI({  userAction:act });

Like every Gigya API method, showShareUI method receives one parameter - params object (learn more about Gigya Basics here).

The params object in the example enfolds the method's only required parameter, which is the UserAction Object that we have constructed in the previous steps.

Note: If you wish to design your own user interface, instead of using our Share add-on, you may use our raw API method socialize.publishUserAction. Learn more here.

The Published User Action on Social Networks

This section shows the user action, which we have constructed in the above example, as it appears when published on the various social networks.

For additional information on how the different Social Networks interact with your data, as well as character length restrictions, please refer to Sharing Limitations.

Facebook


  

 

Note: The name of the Facebook app (in this example, "Gigya Examples") is a link back to the Facebook app, but the actual destination of the link depends on how your app is configured. If your Facebook app includes a Canvas page, the link leads to that Canvas page (see Facebook External Application Canvas Page for more information). If the app has no user-facing page within Facebook, the link leads to the site URL or mobile URL you have defined for the app.

 

Twitter

 

LinkedIn

 

A Working Code Example

In the Share add-on demo you will find a complete working example of a web-page/widget that publishes user actions using the Share add-on. You may view the code, run it and view the outcome.

 

Learn More