Was this article helpful?

Sharing via Email

Last modified 08:31, 20 Aug 2014

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 plugin (see screenshot below). When the user clicks the "Email" button, the Share plugin 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 plugin will automatically close.

ShareUI_Email-html.gif

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, URL links unrelated to the API's base domain or links to inaccessible URLs. When working with test systems, take care to use the correct URLs.

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

SimpleShare_email.gif

 

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 plugin. The default email body appears as follows:

Email.gif

 

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

 

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 plugin.
  • $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 plugin.
  • $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.

Share_EmailBodyParameters-html.gif

 

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 plugin 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 Plugin either in Simple or Multiselect mode according to the user connection status. 
			    ,snapToElementID: "btnShare" // Snaps the Simple Share Plugin 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 Plugin 
			};

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

		}
		
		// onError event handler
		function onError(event) {
		    alert('An error has occured' + ': ' + 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>

 

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 plugin 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 in order to make sure that emails that are sent through Gigya Share arrive to their destination, and not a spam folder. 

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

email-captcha.png

 

 

Sending the Email from your Own Server

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);
        }
}
Was this article helpful?
Pages that link here
Page statistics
11472 view(s) and 11 edit(s)
Social share
Share this page?

Tags

This page has no custom tags set.

Comments

You must to post a comment.

Attachments