Rewards Social 2.0 Integration

Automatic Integration

We know how crucial social media is to our merchants and how much it drives their online marketing. For this reason, we’ve built out-of-the-box support for a number of social media sharing buttons. These include native Facebook, Twitter, Google+ and Pinterest sharing buttons. In addition to these native buttons, we also support social buttons supplied by the following vendors:

Rewards Social 2.0 can automatically detect supported social buttons anywhere on the page and process rewards actions for them. There are however, some special cases where it’s ambiguous what kind of rewards action a particular social button should process. In these cases, we’ll need an explicit way of identifying the social buttons:  

Special Case 1: Post-Purchase Sharing

Our existing purchase sharing feature allows customers to share a purchased product on Facebook and Twitter in exchange for rewards. To distinguish these sharing buttons from normal Facebook Share and Twitter Share buttons on the page, these buttons must be enclosed in an HTML tag which has data-order and data-product attributes, representing the Magento Order Id and Magento Product Id respectively.

For Example

<div data-order=”123” data-product=”456”>
    <!-- insert supported sharing buttons here -->
</div>
	

Your front-end developer will need to generate the HTML container above, through a phtml template file for the correct Magento Order Id and Product Id to be available.

Special Case 2: Referral Code Sharing

With our existing referral share feature which rewards customers for sharing of their referral code via Twitter and Facebook, we have a similar setup, in that we need to distinguish these kinds of buttons from regular ones. We expect these buttons to be inside an HTML tag which contains a data-st-referral attribute.

<div data-st-referral>
    <!-- insert supported sharing buttons here -->
</div>
	

Customizing MageRewards's Social Buttons

Although we’re now able to detect supported social buttons anywhere on the page, you might still want to consider changing the default social buttons that come bundled with MageRewards. This will allow you to explicitly control which buttons show where, and also saves you from guessing where the buttons should go, especially for the special cases above.

Located under the template path app/design/frontend/base/default/template/rewardssocial2/themes you will notice a set of default template files for each social button. To customize these templates:

  1. Copy the default folder into your theme directory, at the path below:
    app/design/frontend/<your_package>/<your_theme>/template/rewardssocial2/themes/
  2. Modify template contents of the default folder in the new location, with your customized buttons.

Note

If your new buttons are not automatically detected as reward-able social buttons by MageRewards, you will need to perform manual front-end integration on them as described below.

Manual Frontend Integration

In cases where your customized social buttons are not automatically detected and rewarded for, you’re able to use two different alternatives to integrate your social icons with MageRewards:

  • The first alternative is adding HTML5 data attributes to your customized buttons.
  • Your second alternative is to use our Rewards Social 2.0 JavaScript API.

You’ll likely need help from a front-end developer to modify your template files for these.

HTML5 Data Attributes

As of MageRewards v1.8.8.0, you're able to add a data-st-social-action attribute to any HTML element while specifying the desired social action as it's value. MageRewards will recognize the element and carry out the social action once the element is clicked. Hovering on the element will also automatically set and clear the social message on the page. List of acceptable values are:
  • facebook_like
  • facebook_share
  • twitter_follow
  • twitter_tweet
  • google_plusone
  • pinterest_pin

Referral Code Sharing and Purchase Sharing

To reward for Referral Code Sharing and Purchase Sharing specifically, you'll need to also include the appropriate data attributes for each, as described earlier in Automatic Integration.
See examples below.

Examples
<!-- Example 1: -->
<button data-st-social-action="facebook_share" data-order="1400020" data-product="39">
   Facebook Share Purchase
</button>

<!-- Example 2: -->
<div data-order="123" data-product="456">
    <button data-st-social-action="twitter_tweet">
        Twitter Tweet Purchase
    </button>
</div>

<!-- Example 3: -->
<button data-st-social-action="twitter_tweet" data-st-referral>
    Facebook Referral Code Sharing
</button>

<!-- Example 4: -->
<div data-st-referral>
    <button data-st-social-action="twitter_tweet">
        Twitter Tweet Referral Code Sharing
    </button>
</div>
	

JavaScript API Documentation

The JavaScript API provides a more advanced way to integrate your social buttons with MageRewards. This is especially useful if you'd like to implement a much more interactive way of rewarding for social actions or if you’ve deliberately turned off automatic integrations.
MageRewards.social.doAction(action, data)
Available as of MageRewards 1.8.8.0
Will trigger the specified social action and tell Magento once the social action is carried out.
Parameters
action (string)
Specify which social action to perform
List of acceptable string options are:
  • facebook_like
  • facebook_share
  • twitter_follow
  • twitter_tweet
  • google_plusone
  • pinterest_pin
  • facebook_share_purchase
  • twitter_tweet_purchase
  • facebook_share_referral
  • twitter_tweet_referral
data (object)
Some of the action items above require extra data. Specifically,
  • facebook_share_purchase :
    • order(int)
    • product(int)
  • twitter_share_purchase :
    • order(int)
    • product(int)
Results
A pop-up window or modal belonging to the social network will appear, prompting the specified social action from the user.
As well, an Ajax call is made to a Magento front-end controller to notify MageRewards of the social event. The response is either a 200 success with no content, or an http error code with reason for failure.
Example
MageRewards.social.doAction(“facebook_share_referral”, {
    order: 123,
    product: 123
});
		
MageRewards.social.registerEvent(action, data)
Tells Magento that a social action has occurred.
Parameters
action (string)
Specify which social action has recently occurred.
List of acceptable string options are:
  • facebook_like
  • facebook_share
  • twitter_follow
  • twitter_tweet
  • google_plusone
  • pinterest_pin
  • facebook_share_purchase
  • twitter_tweet_purchase
  • facebook_share_referral
  • twitter_tweet_referral
data (object)
Some of the action items above require extra data. Specifically,
  • facebook_share_purchase :
    • order(int)
    • product(int)
  • twitter_share_purchase :
    • order(int)
    • product(int)
Results
An Ajax call is made to a Magento front-end controller to process the event. The response is either a 200 success with no content, or an http error code with reason for failure.
Example
MageRewards.social.registerEvent(“facebook_share_referral”, {
    order: 123,
    product: 123
});
		
MageRewards.social.showEarningMessage(action, target)
MageRewards will display an earning message notification beside social buttons if there’s an active reward rule for the given action.
Parameters
action (string)
Specify which action to show the reward earning message for.
Available options are:
  • facebook_like
  • facebook_share
  • twitter_follow
  • twitter_tweet
  • google_plusone
  • pinterest_pin
  • facebook_share_purchase
  • twitter_tweet_purchase
  • facebook_share_referral
  • twitter_tweet_referral
target (string) (optional)
An optional css selector string for a custom HTML container to display the message inside. If not specified, default value of .sweettooth-social-messages will be used.
Results
When called, earning points information about the specified action will be displayed. If no earnings are available for the provided action, a value of false is returned and nothing happens on the front-end.
Example
MageRewards.social.showEarningMessage(“facebook_like”, “.myHtmlClass”);
		
MageRewards.social.clearEarningMessage(target)
This is used to clear any previously displayed points earning messages.
Parameters
target (string) (optional)
An optional css selector string for a custom HTML container to clear. If not specified, default value of .sweettooth-social-messages will be used.
Results
When called, the container will be loaded with any content it previously had before showEarningMessage() was executed.
Example
MageRewards.social.clearEarningMessage(“.myHtmlClass”);
		
MageRewards.social.openModal(modal)
This is used to display a specific pop-up modal on the front-end related to Rewards Social 2.0.
Parameters
modal (string)
Specifies which pop-up modal to open. Only available option is refer-friends at the moment.
Results
When executed on any page, the specified pop-up modal will be displayed on the page. If an unsupported modal name is provided, value of false is returned and nothing happens.
Example
MageRewards.social.openModal(“refer-friends”);
		

Manual Integration Examples

Simple Image Tag

For this example we’ll assume the intention is to treat a simple image as a “Facebook Like” button and reward customers for clicking it:

<!-- Alternative 1 -->
<img src=”facebook-like.png”
  onclick="javascript: MageRewards.social.doAction('facebook_like');"
  onmouseenter="javascript: MageRewards.social.showEarningMessage('facebook_like');"
  onmouseout="javascript: MageRewards.social.clearEarningMessage();" />

<!-- Alternative 2 -->
<img src=”facebook-like.png” data-st-social-action="facebook_like" />
	
Interactive Script

For this example we’ll write some JavaScript code which will open a "Facebook Like" window and reward the customer for sharing one of their purchases on Facebook, 10 seconds after current page has loaded.

<script type="application/javascript">
    window.setTimeout(function() {
        MageRewards.social.doAction('facebook_share_purchase', {
            order: 4354,         // Magento Order Id
            product: 457         // Magento Product Id
        });
    }, 10000); // 10 seconds (10000 milliseconds)
</script>
	

Still need help? Get Help Get Help