Sharing via Email

Skip to end of metadata
Go to start of metadata

Description

Gigya offers an option of sharing the user action via email. Sharing via email is provided through the enabling of an "Email" button on the Share add-on (see screenshot below). When the user clicks the "Email" button, the Share add-on presents a "Share via Email" screen. The screen includes a form for the user to enter email details. If the user clicks on the "Send" button, Gigya will send an email that publishes the user action to the selected email contacts, and the add-on will automatically close.

The email support may be enabled by setting the showEmailButton parameter of the showShareUI API method to "true":

var params = { 
    userAction: act,
    showEmailButton: true
};

Note:
Importing contacts from the email provider: The email screen gives the user an option to import contacts from their email provider (see screenshot above). This feature is only available if you checked the Enable retrieving user contacts checkbox in your Permissions page in Gigya's website.

Spam blocking measures: Emails are blocked if they contain banned keywords, non-trusted URL links (i.e links that are unrelated to the API's base domain, not included in the trusted share URLs list and not in the global whitelist) or links to inaccessible URLs. When working with test systems, take care to use the correct URLs.

Email limit: Users can add a maximum of two email addresses. If more than two email addresses are specified, the content will not be shared.

The "Share via Email" screen also opens when the user clicks the "Email" button on the Simple Share screen:

 

The Email Structure

Email Subject

The email subject is taken from the User Action's title field. If this field is not provided then the default email subject text is: "Take a look at this".

Email Body

Gigya defines a default email body structure that is based on the User Action fields, and the message entered by the user in the Share add-on. The default email body appears as follows:

 

The link back URL, the title and the description are taken from the User Action object. The user message is taken from the user message that the user entered in the Share add-on.

Changing the Email Body and Footer

Email Body: You may define an alternative email body using the emailBody parameter of the showShareUI API method. The email body should be defined in HTML format, and may include the placeholders:  $sender$, $URL$, $userMsg$, $title$, $description$, and $actionLinkTitle$. The placeholders in the email body will be replaced by Gigya when the email is sent:

  • $sender$ will be replaced with the sender in the From box that the user entered in the Share add-on.
  • $URL$ will be replaced with the LinkBack field of the User Action.
  • $userMsg$ will be replaced with the user message that the user entered in the Share add-on.
  • $title$ will be replaced with the title field of the User Action.
  • $description$ will be replaced with the description field of the User Action.
  • $actionLinkTitle$ will be replaced with the text of the link back URL of the User Action. Currently uses the fixed text: "Click here", if defined, the value overrides the default text.
     

Email Footer: If you want to add your own branding to the bottom of email shares from your site, you can use the emailBody parameter of the showShareUI API method to customize the text directly above the Gigya footer.

 

For example:

var params = { 
    userAction: act, 
    showEmailButton: true, 
    emailBody: "Hi,<br/> Check this out: $URL$ <br/> $userMsg$ <br/> The title is: $title$ <br/> The description is: $description$ <br/> This email is from: $sender$"
};

Running Example

Here is a running example of the Share add-on with enabled email feature and with the customized email body:

 

 

The Example Code

<html>
<head>
    <style>
	 body {font-family:Arial;font-size: 12px; background-color:#fff; line-height:20px}
	</style>
	<SCRIPT type="text/javascript" lang="javascript" 
	   src="http://cdn.gigya.com/JS/socialize.js?apikey=2_Y82PzwJ_chSFImHXaIDJClnLyJzmk-VFOavSsaNTzl6m901s_NNxRAS0xJ3bd3_N">
	</SCRIPT>
    <script type="text/javascript">

        // Create and Publish User's Action

        // This method is associated with the "btnPublishAction" click
        function showShareUI(operationMode) {

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

		    // Setting the title and description 

		    // (will be presented in the preview on the Share UI)
		    act.setTitle("Gigya - Make your site social.");
		    act.setSubtitle("An overview video");
		    act.setDescription("Gigya's technology makes websites social, integrating online businesses with"
		        + " the top social networks using Facebook Connect, Twitter for Websites, " 
		        + "LinkedIn, Foursquare and more.");

            // Setting a link back to the publishing source
		    act.setLinkBack("http://info.gigya.com/GigyaVideoOverviewForm.html");

		    // Adding Action Link
		    act.addActionLink("Gigya site", "http://www.gigya.com");

			// Adding an image (will be presented in the preview on the Share UI)
	        var image = {
	            src: 'http://info.gigya.com/rs/gigya/images/gigyaN-logo.gif',
	            href: 'http://info.gigya.com/GigyaVideoOverviewForm.html',
	            type: 'image'
	        };
			act.addMediaItem(image);

			// Parameters for the showShareUI method, including the UserAction object
			var params = 
			{
			    userAction: act  // The UserAction object enfolding the newsfeed data.	
				,operationMode: operationMode// Opens the Share add-on either in Simple or Multiselect mode according to the user connection status. 
			    ,snapToElementID: "btnShare" // Snaps the Simple Share add-on to the share button
				,onError: onError  // onError method will be summoned if an error occurs. 
			    ,onSendDone: onSendDone // onError method will be summoned after 
			                        // Gigya finishes the publishing process.
				,context: operationMode			
				,showMoreButton: true // Enable the "More" button and screen
				,showEmailButton: true // Enable the "Email" button and screen
				,emailBody: "This email is from: $sender$ <br/> Check this out: $URL$ <br/> $userMsg$ <userMsg> <br/> The title is: $title$ <br/> The description is: $description$"
    			,useHTML: true  // Use the HTML implementation of the add-on 
			};

			// Show the "Share" dialog
			gigya.socialize.showShareUI(params);
		}

		// onError event handler
		function onError(event) {
		    alert('An error has occurred' + ': ' + event.errorCode + '; ' + event.errorMessage);
		}

		// onSendDone event handler. 

		// Displays in the status field, the list of providers to which the newsfeed has been 

		// successfully published.
		function onSendDone(event)
		{
		    document.getElementById('status').style.color = "green";
			switch(event.context)
			{
				case 'multiSelect':
					document.getElementById('status').innerHTML = 'The newsfeed has been posted to: '  + event.providers;
					break;
				case 'simpleShare':
					document.getElementById('status').innerHTML = 'Clicked '  + event.providers;
					break;
				default:
					document.getElementById('status').innerHTML = 'Share onSendDone' ;
			}
		}
    </script>
</head>

<body>
    <h4>Please click on one of the buttons below to open the "Share" dialog:</h4>
    <input type=button id="btnShare" onclick="javascript:showShareUI('multiSelect')" value="Advanced Share" />&nbsp;&nbsp;
	<input type=button id="btnShare" onclick="javascript:showShareUI('simpleShare')" value="Simple Share" />
    <div id="status"></div>
</body>
</html>

Notes:

In order to make the above code work in your environment, please note:

  • The API key in the sample will only work on http://localhost/...
  • To load the page from your domain, modify the value of the "APIKey" field in the code to your own Gigya API Key. A Gigya API Key can be obtained from the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API Key.
  • If you are using https, be sure to further adjust the js API url to: https://cdns.gigya.com/JS/gigya.js?apikey=<Your_API_Key>.

Customizations

Setting the "Share via Email" Screen as the Default View

You may select the "Share via Email" screen to be the default view to be shown when the Share add-on opens. To do this, set the initialView parameter of the  socialize.showShareUI method to 'email'.
Note: this will only work if the showEmailButton parameter is set to "true".

Code Sample

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

    // Add data to the User Action object
    // ...
    // Share parameters:
    var params = { 
        userAction: act,
        showEmailButton: true,     // Support Email view 
        initialView: 'email'       // Show the Email view as the initial view
    };

    // Show the "Share" dialog
    gigya.socialize.showShareUI(params); 
}

Using CAPTCHA Mechanism for Sending Emails

You may add the option of using an email CAPTCHA. The use of CAPTCHA prevents spammers from using bots to send spam emails from your site.

  • Set the useEmailCaptcha parameter of the showShareUI API method to 'true'.

Sending the Email from your Own Server

Sending emails from your own email server reduces the likelihood of an email share being identified as spam by email providers and is recommended if CAPTCHA is not enabled. 

Usually the Gigya server sends the emails after the user presses the 'Send' button on the email screen. If you wish to send the email by yourself from your own servers, do the following:

  • Set the dontSendEmail parameter to 'true'. This will ensure that Gigya will not actually send the email after the user presses the 'Send' button.
  • Register to the 'onSendDone' event.
  • In the 'onSendDone' event handler, check if the providers field equals {'email'}. If so, use the recipients, sender and userMessage data fields to send the email from your server.

Code Sample

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

    // Add data to the User Action object
    // ...
    // Share parameters:
    var params = { 
        userAction: act,
        showEmailButton: true,
        dontSendEmail: true,             // Instruct Gigya not to send the email
        onSendDone: onSendHandler       // Register to the 'onSendDone' event
    };

    // Show the "Share" dialog
    gigya.socialize.showShareUI(params); 
}

// onSendDone event handler. 
function onSendHandler(event)
{
	if (event.providers == 'email') {
            alert("Sender: " + event.sender + "  User Message: " + event.userMessage + " First recipient's email: "  + event.recipients[0].email);
        }
}