Showmybuy integration
for partners

The partner account integration is targeted to webshop providers that hosts or manages multiple webshops.

OVERVIEW

Integrating Showmybuy can be done in two different ways:

  1. As stand-alone webshop
  2. As a partner

First read up on the basics of integrate a stand-alone webshop since it provides the basics for integrating Showmybuy as a partner.

GETTING A PARTNER ACCOUNT

To integrate Showmybuy, the first thing you need is a partner account to get access to the Showmybuy control panel. If you don’t already have a partner account please visit our partner page and apply for one now.

Integrating a webshop

You will need the partner-api-id and partner-api-secret which you can find in top left corner under Developers’ section.

Partner API info available in the Developers’ section.

INVITING YOUR FIRST WEBSHOP

The webshop that you wish to belong to the partner account must be invited from within the partner account.
Go to the webshops section and click invite new webshop.

Webshops belonging to the partner are invited from within the account.


Notes:

  • Webshop domain is the base domain name for the webshop. It is important that you use the real domain name of the webshop since it will be used in some domain configurations within Showmybuy.
  • ApiId is your unique identifier of this webshop. It will be used in integration to identify the webshop’s account
GETTING ACCESS TO THE WEBSHOP

From the webshops section, partners can easily login to the webshop’s account and operate it as a normal webshop account user.

Partner getting access to webshop’s account.

Integrating Showmybuy flyout in a webshop

The easiest way to integrate and test a first integration of a webshop is by accessing the webshop and create a test deal. Read Create first deal to see how it is done. The only difference between integrating a stand-alone webshop and a webshop belonging to a partner is how the api-id is being used.

INSTALLING SHOWMYBUY ON THE ORDER
CONFIRMATION PAGE WITH PARTNER ID

The order confirmation page is the page shown to a webshop’s 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).
  "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/PARTNER-API-ID_WEBSHOP-UNIQUE-ID/en" async="async"></script>
</head>
<body>
Thank you for your order.
</body>
</html>
Congratulations!

After having tested the webshop in test-mode, simply turn it into production-mode and your webshops are ready to go. Having integrated to this point gives your webshops access to the Showmybuy flyout but they still have to handle their rewards manually. If you are concerned about security please read the optional security section. Continue reading to see how to enable automatic reward handling.

Enable automatic reward handling for your webshops

Defining reward implementations

As a partner you often have full control over what kind of rewards that could be handled by the underlying system of your webshops. We recommend partners to provide at least one reward implementation. The part of the API that handles reward implementations put no limitations for what kind of rewards that can be implemented. But for your convenience we have put together a little list of inspiration.

FREE DELIVERY

When a consumer has fulfilled a deal the webshop subtracts the cost of shipping for the current order. Make sure that the payment system being used supports an adjustment of the order value some time after payment.

DISCOUNT COUPON

When a consumer has fulfilled a deal the webshop generates a discount coupon i.e. a discount code, in percent or cash-value, to be used at a future purchase. The discount code is sent to the email address of the current order. The implementation should be parameter based for the webshop account user to set the discount value of the generated discount code.

DISCOUNT OF CURRENT ORDER

When a consumer has fulfilled a deal the webshop substracts an amount from the order value. Make sure that the payment system being used supports an adjustment of the order value some time after payment. The implementation should be parameter based for the webshop account user to set the discount value to be subtracted from the order value.

FREE GIVE AWAY

When a consumer has fulfilled a deal the webshop adds a physical product, defined by a product-id/article-id, to the current order. In this case the webshop owner must configure the deal to end within the shipping hours so that it’s possible to add the product to the order before being shipped. The implementation should be parameter based for the webshop account user to define the productId of the product to be added to the order.

MEMBERSHIP POINTS

When a consumer has fulfilled a deal the webshop adds membership points to the user profile of the current order. You may use a parameter to dynamically calculate the amount of membership points given, based on the total order value.

OTHER REWARD IMPLEMENTATIONS

As stated earlier the API does not put any restrictions of how a reward should be implemented nor how it should reward the consumer. The API provides an optional parameter sent to the reward implementation, at runtime, that is configurable in the deal editor. A reward implementation may use the parameter in any way to dynamically calculate the result of the implementation’s execution.

Webshop management

Webshops may be managed in the partner account control panel but for some tasks Showmybuy provides a more technical API. Webshop management is done by JSON documents that may be submitted via the Showmybuy control panel.

To submit JSON documents via the Showmybuy control panel, navigate to the Developers section.

CONFIGURE SUPPORTED REWARD IMPLEMENTATIONS

For a webshop to support automated rewards, one or more reward implementations must be configured. The partner API allows configuration of reward implementations with the setRewards JSON document.

Note:Reward implementations can also be registered by accessing the webshop from the partner account and navigate to the webshop’s developers section.

{
    "cmd" : "setRewards",
    "webshopApiId" : "star_show_shoes",
    "removeAll" : true,
    "rewards" : [
        {
         "id" :"FREE_SHIPPING",
         "type" : "SHIPPING",
         "name" : "Free shipping",
         "desc" : "Removes shipping costs from the order",
         "icon" : "SHIPPING",
         "url" : "https://www.starshowshoes.com/showmybuy_reward_path"
        },
        {
         "id" : "GIVEAWAY_BY_ID",
         "type" : "GIVEAWAY",
         "name" : "Free give away",
         "desc" : "Adds a free item to the order before shipping",
         "icon" : "GIVEAWAY",
         "param" : {
             "type" : "string",
             "desc" : "Article/ProductId"
         },
         "url" : "https://www.starshowshoes.com/showmybuy_reward_path"
        }
    ]
}
Notes:

  • Line 4 : Existing reward implementations will be removed before adding the implementations in this request.
  • Line 8 : Supported types for rewards are [COUPON, DISCOUNT, SHIPPING, GIVEAWAY, POINTS and OTHER]
  • Line 11 : Supported types for icons are [SHIPPING, COUPON_GENERIC, COUPON_PERCENT, COUPON_AMOUNT, DISCOUNT_GENERIC, DISCOUNT_PERCENT, DISCOUNT_AMOUNT, GIVEAWAY, POINTS and OTHER
  • Line 21 : Supported types for the optional reward parameter are [decimal,percent,integer,string].
  • Omitting the param definition (line 20-23) instructs Showmybuy that the reward implementation is not configurable in the deal editor and the reward request sent by Showmybuy will have rewardValue=null

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:

  • Line 6 and 10: Uses the webshop’s e-commerce platform to access the correct order information.
  • Line 9: Gets the value for the coupon from the request.

TESTING REWARD IMPLEMENTATIONS

Showmybuy provides a testing tool to simulate the reward generation urls in a real scenario in the developers section.

Select a webshop from the drop down list and all registered reward implementations will show. Click the test url button to test the reward implementation.

Optional security

To make sure no one registers usage statistics with the webshop’s account, a security enhancement may be configured for the account. To activate javascript security, access the webshop from the partner account and go to the webshop’s developer section.

Javascript security configured in the developer section.

To secure your installation, have the server compute the MAC value of the purchaseId with your api-secret and include it with the window.smbConfig javascript code.
$orderId = "order1234";
$secureToken = hash_hmac("sha256",PARTNER-API-ID . '#' . $orderId,$PARTNER_API_SECRET);
        string orderId = "order1234";
        string message = PARTNER-API-ID + "#" + orderId;
        HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(PARTNER-API-ID));
        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/PARTNER-API-ID_WEBSHOP-UNIQUE-ID/en"></script>
</head>
<body>
Thank you for your order.
</body>
</html>

Additional features

MEASURING SHOWMYBUY TRAFFIC

Showmybuy allows partners to redirect consumer traffic to their own systems for measuring Showmybuy performance.
Navigate to the webshops section and select the webshop you want to add the redirection for and click the edit button.

Note: It’s very important that the partners integration forwards the visiting friend to the {purchaseUrl} provided in the link to the measuring system.

It’s possible to redirect consumer traffic for further analysis by the partner.