Showmybuy development for stand-alone webshops

The first thing you need to integrate Showmybuy is an account to get access to the Showmybuy control panel. You should have received an invitation email for the account by your webstore. If you don’t already have an account please visit our signup page to create one now. You will need the api-id which you can find in the control panel’s Developer section.

Webshop API info available in the Developers section.

To ensure that the account is in test-mode, navigate to the deals section and verify that the test-mode note appears on the top of the page.

Test-mode note appearing in the deals section when account is in test-mode.

CREATING YOUR FIRST DEAL

If you are not familar with the Showmybuy concept please take a moment and watch the Showmybuy movie. The movie will give you a good overview of the Showmybuy consumer experience and the control panel.

Before you start the integration work, a deal must exist and be set in On mode from the deals section. To create a deal, perform the following steps:

  1. Navigate to the Deals section and click Create a reward deal button. If your user lacks access to the deal editor, ask another account member to create a deal for you.
  2. Execute the steps 1-4 in the deal editor. You may choose any kind of reward in section 1.
  3. Click the Save deal button.

You should be taken back to the deals section and you should see a preview of your new deal.

Deal section after creating a first test deal

To start your integration work set your deal online by clicking the On/Off button on the deal.

Deal section informing that a deal is On and ready to be rendered in your webshop.

Integrate Showmybuy
in a couple of minutes

This section will guide you through the minimum requirement for installing Showmybuy on your webshop’s order confirmation page.

INTEGRATING SHOWMYBUY ON THE ORDER CONFIRMATION PAGE

The order confirmation page is the page shown to your customer after a purchase has been done. Add the following javascript snippet to the HTML of your order-confirmation page to render and configure the Showmybuy flyout.

<html>
<head>
<script type="text/javascript">
 window.smbConfig = {
  "purchaseId" : "order1234",                               // Webshop's unique identifier of the order.
  "email" : "consumername@somedomain.com",                  // Email address of your consumer. (optional) (See note below).
  "products" : [
   {
    "productUrl" : "http://www.shop.com/products/product1", // Url to the purchased product's page (required)
    "imageUrl" : "//www.shop.com/images/product1",     // Url to the purchased product's image (required)
    "name" : "The first product's name"                     // Name of the purchased product (optional)
   }
   // If multiple products are purchased add them here in the products array.
  ]
 };
</script>
<script type="text/javascript" src="//i.showmybuy.com/api/v3/web/WEBSHOP-API-ID/en" async="async"></script>
</head>
<body>
Thank you for your order.
</body>
</html>

Notes

  • If no deal is showing, make sure a deal is in mode On in the deal section as described in Creating your first deal.
  • If multiple items are purchased, simply add more products to the smbConfig.products array. In case of multiple products, Showmybuy will let the customer select which product he/she wants to show before sharing.
  • Important information about consumer email address. Showmybuy offers rewards that Showmybuy sends directly to the consumer after having fulfilled the deal. If no email is defined the consumer is asked to fill in their email address. We strongly recommend adding email to smbConfig since greatly improves the number of shared purchases. Showmybuy will not use the email address for any other purpose.
  • The last url parameter defines the language that the flyout should be loaded in. If it is not defined, or defined with a non-existent language code for the flyout, the default (first defined language for the deal) will be used. Showmybuy uses standard ISO 639-1 language codes.
  • It is good practice to put external javascript references within the <HEAD> section of a HTML page. Some people argue that putting javascript references in the end of the page, right before the </body> tag, speeds up page loading. It’s all about taste – The Showmybuy javascript library functions in both places.

If integration is successfull the flyout should be visible when the page has loaded. In test mode, some debug info is written to the javascript window.console.

Flyout showing after integration on order confirmation page.

TESTING YOUR INSTALLATION

Your integration work for the flyout is now done and it’s time for testing.

  1. Perform a purchase to come to the order-confirmation page. You should see the flyout with social media icons visible for sharing the purchase.
  2. Click on any of the social media icons to share the purchase. A developer test page will appear. Verifiy the product url, image url and product name.
  3. Copy the Showmybuy URL and paste into a browser window to make sure that your product page is loading.
  4. If your deal requires 1 unique visitor a reward should be visible in the Rewards section of the Showmybuy control panel within a minute. (In production mode Showmybuy disrespects clicks from the same IP-address that shared the purchase).
  5. If your webshop allows customers to purchase multiple products perform the same test over again with 2 or more items in shopping cart. Showmybuy should present the Product chooser before coming to the developer screen.


Sharing a purchase in test-mode brings up the developer test page before continuing to the requested social network.

Congratulations!

You now have Showmybuy in your webshop! Feel free to play around with the deal editor and create deals that your customers can’t resist.

Handling rewards

When your customer has fulfilled his/her part of the deal (bringing the required number of friends to check out the purchased product) it’s time for the webshop to pay the promised reward to the customer. In our minimal installation, the reward must be handled manually in the Rewards section in the Showmybuy control panel. After manual handling by the webshop, a simple click on the Completed button marks the reward as handled.

The Rewards section shows rewards that must be handled manually.

For larger webshops, with higher volumes of rewards, please read the implementing automatic reward handling section below.

Optional features
of Showmybuy

Showmybuy is designed to be easy to try out and great to grow with. The installation above defines the minimum effort required to start to drive traffic but the Showmybuy platform offers more functionality to meet your needs.

Adding the Showmybuy
flyout before payment

Showmybuy enables webshops to give their customers a better deal! Depending on your webshop’s Showmybuy offer it may just be enough to bring an almost customer into a purchasing customer. To give customers a preview of the upcoming Showmybuy deal, available to them after payment, include the following javascript snippet to the webshop’s before purchase pages.

<html>
<head>
<script type="text/javascript" src="//i.showmybuy.com/api/v3/web/WEBSHOP-API-ID/en" async="async"></script>
</head>
<body>
Webshop front- or checkout page.
</body>
</html>
Notes

  • You may put the Showmybuy javascript on every page in your webshop. Once the Showmybuy flyout has been shown to the customer before payment and the customer clicked it away it will no longer be shown until the customer comes to the order confirmation page.
  • By default the Showmybuy flyout is only shown once before appearing on the order confirmation page. Include the window.smbConfig.reset=true to reset the Showmybuy flyout and put it back in a visible state.
Logon to your Showmybuy account and update your developer settings to enable Showmybuy flyout before purchase.

Adding Showmybuy parameters to your product Url

Showmybuy may populate the productUrl with Showmybuy parameters before forwarding the visiting friend to the webshop. This can be useful for internal tracking in your webshop.

<html>
<head>
<script type="text/javascript">
    window.smbConfig = {
       "purchaseId" : "123",
       "email" : "someone@somedomain.com",
       "products" : [
            {
                "name" : "Product name",
                "productUrl" : "http://www.someshop.com/product/abc?utm_campaign={smb:source}",
                "imageUrl" : "http://cdn.someshop.com/images/abc_big.png",
            }
       ]
    };
</script>
<script type="text/javascript" src="//i.showmybuy.com/api/v3/web/WEBSHOP-API-ID/en" async="async"></script>
</head>
<body>
Webshop front- or checkout page.
</body>
</html>

Supported parameters

  • {smb:source}: Replaced with the source network identification (facebook, googleplus, twitter, linkedin or url)
  • {smb:lang}: Replaced with the ISO language code for the language that the purchase was shared in (facebook, googleplus, twitter, linkedin or url)
  • {smb:pruchaseId}: Replaced with webshop’s purchaseId for the shared purchase.

Implementing automatic reward handling

When a customer has fulfilled his/her part of the deal, Showmybuy triggers a reward event to be handled by the webshop. A reward may be anything(not limited to) from Discount-cash-coupon, Free-delivery, Member-points or a Free-give-away. If no automatic reward handling is implemented for a webshop, the reward has to be handled manually by the Showmybuy account users in the Rewards section. The reward API does not put any constraints of what kind of rewards that can be implented.

REGISTERING A REWARD IMPLEMENTATION
IN THE SHOWMYBUY ACCOUNT

After a reward implementation has been completed it must be registered in the Showmybuy account to inform the Showmybuy deal-makers that the automatic reward handling exists.

To register a reward implementation, log on to the control panel and navigate to the Developers’ section.

  1. Click the Add reward implementation button.
  2. Select type of reward. If there is no suitable reward type for your reward implementation choose the other option.
  3. Choose a Reward id. This is the id that the Showmybuy server will send with the reward request to your reward implementation. In the example above the rewardId is COUPON_PERCENT.
  4. If you want the reward to be configurable with a parameter in the deal-editor select the parameter type and give it a name. If your reward implementation is not configurable select the void option.
  5. Define the Reward generation url to your server that the Showmybuy servers will call for a reward to be generated.
  6. Test the reward implementation with the testing tool. Make sure you get status of complete. It’s good practice to test both positive and negative use-cases.
  7. Provide descriptive deal-maker information to be understood by deal-makers in the deal editor.
  8. Select a suitable icon.
  9. Register the reward implemenation with the system by clicking the Register reward implementation button.

Notes
Showmybuy comes with a few pre-registered rewards in the deal editor. These rewards don’t have any implementations connected to them and will show up together with a manual-handling-required warning if used in the deal editor.
You may override a pre-registered reward by selecting it from the override reward select box in the reward implementation dialogue. If you override a pre-registered reward, the warning of manual handling will disappear from the deal editor.

IMPLEMENTING AN AUTOMATIC REWARD

When a reward event is triggered, the Showmybuy servers will invoke a url with a JSON http(s) POST payload on your webshop, to handle the reward.

	$body= file_get_contents('php://input');
	if($params = json_decode($body)) {
		$purchaseId = $params->purchaseId;
                $mode = $params->mode; // 'test' or 'production'
		try {
			$order = $YOURSYSTEM::findOrder($purchaseId);
			$rewardId = $params->rewardId;
			if($rewardId==='COUPON_PERCENT') {
				$percent = $params->rewardValue;
				$coupon = $YOURSYSTEM::generateCoupon($percent);
				$YOURSYSTEM::sendCoupon($coupon,$order->email);
				$response = array(
					"status" => true, // Reward was successfully handled
					"message" => "Coupon $percent (%) sent to {$order->email}" // Optional message to reward section.
				);
				echo(json_encode($response));
			} else {
				throw new Exception("This reward implementation does not support rewardId $rewardId");
			}
		} catch(Exception $e) {
			$response = array(
				"status" => false,  // Reward could not be handled
				"message" => $e->getMessage()  //Optional message to reward section.
			);
			echo(json_encode($response));
		}
	}
//JSON request
{
    "purchaseId" : "order1234",
    "rewardId" : "COUPON_PERCENT",
    "rewardValue" : 10,
    "mode" : "production"
}

//JSON response
{
    "status" : true,
    "message" : "Coupon 10 (%) sent to someone@somemail.com"
}
//JSON request
{
    "purchaseId" : "order1234",
    "rewardId" : "COUPON_PERCENT",
    "rewardValue" : 10,
    "mode" : "production"
}

//JSON response
{
    "status" : false,
    "message" : "Order1234 could not be found"
}

Notes On line 5,9 and 10 the implementation uses the webshop’s e-commerce platform to generate and send the discount-coupon to the email of the given order.

Securing your callback

Showmybuy does not dictate any security requirements for your callback implementation. The following guidelines will secure your callback implementation against replay- and man-in-the-middle attacks.

  • Require that your callback implementation is called over HTTPS only.
  • Add a your own shared token on the URL for your callback. Ex: https://backend.yoursystem.com/showmybuy_callback?token=YOUR_SECRET

Before processing the JSON reward data in your callback assert the following conditions:

  • Callback URL is invoked over HTTPS.
  • Invoked URL contains your token and that it equals YOUR_SECRET.

Optional security

To make sure no one registers usage statistics with your webshop account, a security enhancement may be configured for the account. To activate javascript security, go to the developer section.

Javascript security configured in the developer section.

To secure your installation, have the server compute the MAC value of each purchaseId with your api-secret and include it with the window.smbConfig javascript code.
$orderId = "order1234";
$secureToken = hash_hmac("sha256",$WEBSHOP_API_ID . '#' . $orderId,$WEBSHOP_API_SECRET);
        string orderId = "order1234";
        string message = WEBSHOP_API_ID + "#" + orderId;
        HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(WEBSHOP_API_SECRET));
        byte[] bytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
        StringBuilder signature = new StringBuilder();
        for (int i = 0; i < bytes.Length; i++) {
                signature.Append(bytes[i].ToString("x2"));
        }
        string secureToken = signature.ToString();
Add the secure token to the smbConfig on the orderconfirmation page.
<html>
<head>
<script type="text/javascript">
  window.smbConfig = {
    "purchaseId" : "order1234",                                     // Webshop's unique identifier of the order.
    "products" : [
      {
        "productUrl" : "http://www.yourshop.com/products/product1", // Url to the product page (required)
        "imageUrl" : "http://www.yourshop.com/images/product1",     // Url to the product image (required)
        "name" : "The product's name"                               // Name of the product (optional)
      }
    ],
    "secure" : "<?=$secureToken?>"
  };
</script>
<script type="text/javascript" src="//i.showmybuy.com/api/v3/web/WEBSHOP-API-ID/en"></script>
</head>
<body>
Thank you for your order.
</body>
</html>