Developers

Overview

Friendbuy can be integrated in the following ways:

  • Webhooks - Webhooks are callbacks from Friendbuy's servers to your server. For example, you can use Friendbuy's Conversion Webhooks for reward fulfillment by depositing credit into a customer's account after a referral conversion. Learn more about Conversion Webhooks.
  • SmartPixel - The SmartPixel is Friendbuy's Javascript library which is deployed on your site. The SmartPixel allows you to surface widgets and track conversions.
  • REST API - The REST API allows you to query the Friendbuy's servers for data about shares, conversions, and referral links. You can also use the REST API to create sharable links and to track conversions.

The Friendbuy quickstart guides help you to get up and running with minimal fuss. We’ve picked some of the basic implementations and written up step-by-step instructions. If you already know what you’re doing, head over to the SmartPixel Reference or the Rest API Reference for a technical deep-dive.

We love developers, and we want to help. If you have any issues, head over to support and let us know.

Create developer account


Quickstarts

Although you can use Friendbuy to build out a totally custom sharing and referral campaign, we have picked out a few of the common use cases:


Post Purchase

Post Purchase sharing is the most common Friendbuy implementation. By setting up a widget on the "thank you" page you can provide customers a way to promote their purchase. Setting up an incentive program is a popular option, but not required.

1. Get the Widget Code

The first thing you’ll need to do is generate the code for the Post Purchase widget. Log in to your Friendbuy account and create a new widget. Go through the prompts to choose a theme and customize the message. After that you’ll see an option to get the code.

2. Customize Code

Once you have the widget code, you’ll need to customize it for your environment. In this Quickstart we’re going to assume that the system is running on PHP and there is a variable called $order that contains information about the order and customer. In the code sample below, we’ve used PHP code to pass the order ID, amount, and customer ID into the Friendbuy widget code. This is what the completed code looks like:

<script type="text/javascript">
    window['friendbuy'] = window['friendbuy'] || [];
    window['friendbuy'].push(['site', 'site-fffffff-host']);
    window['friendbuy'].push(['track', 'order',
        {
            id: '<?php echo $order->getId() ?>',
            amount: '<?php echo $order->getSubtotal() ?>'
        }
    ]);

    window['friendbuy'].push(['track', 'customer',
        {
            id: '<?php echo $order->getCustomerId() ?>'
        }
    ]);

    window['friendbuy'].push(['widget', 'my_widget_identifier']);

    (function (f, r, n, d, b, y) {
        b = f.createElement(r), y = f.getElementsByTagName(r)[0];b.async = 1;b.src = n;y.parentNode.insertBefore(b, y);
    })(document, 'script', '//djnf6e5yyirys.cloudfront.net/js/friendbuy.min.js');
</script>

Note that we are only customizing the information in the track directives. The rest of the JavaScript is left as it was generated by Friendbuy.

When you have your widget code customized, you’ll need to place it in the head of your document, like so:

<head>
    <!-- css, javascript, meta tags, etc. -->
    [Place Friendbuy JS here]
</head>
<body>...

3. Place the Button

The last thing you need to do for the Post Purchase widget is place the share button on your page. You can put the button anywhere you would like. For our example we’ll place it on our page directly beneath the heading for the page:

<body>
    <h1>Thank You</h1>
    <div class="friendbuy-my_widget_identifier"></div>
    ...
</body>

Note that there is nothing within the div, it is just used as a placeholder and the actual button will be placed by the JavaScript when it executes in the browser.

Wrap Up

Now you see how easy it is to get a Post Purchase sharing widget set up with Friendbuy. Start by designing the widget in the application, then grab the code and customize it for your eCommerce system. Finally, place the share button where you want it to appear on the site. Remember that you are able to edit copy and design of the widget from within Friendbuy at any time without needing to edit the code on your page.

Once you have the Post Purchase code on your site it is a good idea to run a test by making a purchase and sharing it. Log into Friendbuy to make sure that the correct order ID, amount, and customer ID were captured.


Custom Parameters

Friendbuy supports the passing of additional information that you want included with shares and referrals. A common example is passing an offer or coupon code for the person that shared their purchase.

1. Add Parameters to Widget Code

When you provide custom parameters, Friendbuy will include them in the referral URLs that are created. In the example below, the widget whose identifier is my_widget_identifier is being configured with two custom parameters called ref and survey.

    window['friendbuy'] = window['friendbuy'] || [];
    ...
    window['friendbuy'].push([
        'widget', 'my_widget_identifier',
        {
            parameters: {
                ref: '<?php echo $order->getReferralCode() ?>',
                survey: '<?php echo $order->isSurvey() ?>'
            }
        }
    ]);

2. Receive Query String Parameters

When someone clicks on a shared link, a query string parameter will be added for each of the custom parameters provided. Here is what the URL looks like with the ref and survey parameters that were provided (let’s assume the referral code was 'baz-inga' and the survey was completed).

http://yoursite.com/?utm_campaign=...&ref=baz-inga&survey=true

Wrap Up

As you can see, it is simple to send custom parameters to Friendbuy and have them included in the referral links that are generated. You can use these parameters to track additional referral information in your reporting and analytics tool, or even use them to trigger custom views and events on your site. To put everything in context, here is an example of the entire JavaScript snippet including custom parameters:

<script type="text/javascript">
    window['friendbuy'] = window['friendbuy'] || [];
    window['friendbuy'].push(['site', 'site-fffffff-host']);
    window['friendbuy'].push(['track', 'order',
        {
            id: '<?php echo $order->getId() ?>',
            amount: '<?php echo $order->getSubtotal() ?>'
        }
    ]);

    window['friendbuy'].push(['track', 'customer',
        {
            id: '<?php echo $order->getCustomerId() ?>'
        }
    ]);

    window['friendbuy'].push([
        'widget', 'my_widget_identifier',
        {
            parameters: {
                ref: '<?php echo $order->getReferralCode() ?>',
                survey: '<?php echo $order->isSurvey() ?>'
            }
        }
    ]);

    (function (f, r, n, d, b, y) {
        b = f.createElement(r), y = f.getElementsByTagName(r)[0];b.async = 1;b.src = n;y.parentNode.insertBefore(b, y);
    })(document, 'script', '//djnf6e5yyirys.cloudfront.net/js/friendbuy.min.js');
</script>

Product Share

The Product Share is for allowing visitors to your site—who are not necessarily customers yet—to share a specific product. Since the share can be performed from any product page it allows for easier referrals than a post-purchase share. The Product Share makes it easy to let your promoters reach others, because they will have the opportunity to share without needing to go through a checkout process. Note: You can also share product information in a Post Purchase share, not covered in this quickstart.

1. Get the Widget Code

The first thing you’ll need to do is generate the code for the widget. Log in to your Friendbuy account and create a new widget, you’ll want to select the Product Widgets type on the first screen. The theme you choose will control whether the current product or a previously configured “Promotion” is shown. After customizing the widget you’ll see an option to get the code.

2. Customize Code

Once you have the widget code, you’ll need to customize it for your environment. In this Quickstart we’re going to assume that the system is running on PHP and there is a variable called $product that contains information about the specific product. Note: we are also assuming a variable called $user that identifies the current user. This is optional but we recommend you pass an identifier for the current user whenever you can. Without an ID, Friendbuy cannot identify the sharer responsible for a conversion.

<script type="text/javascript">
    window['friendbuy'] = window['friendbuy'] || [];
    window['friendbuy'].push(['site', 'site-fffffff-host']);
    window['friendbuy'].push(['track', 'products',
        [
            {
                sku: '<?php echo $product->getSku() ?>'
            }
        ]
    ]);

    window['friendbuy'].push(['track', 'customer',
        {
            id: '<?php echo user->getId() ?>'
        }
    ]);

    window['friendbuy'].push([
        'widget', 'my_widget_identifier'
    ]);

    (function (f, r, n, d, b, y) {
        b = f.createElement(r), y = f.getElementsByTagName(r)[0];b.async = 1;b.src = n;y.parentNode.insertBefore(b, y);
    })(document, 'script', '//djnf6e5yyirys.cloudfront.net/js/friendbuy.min.js');
</script>

Note that we are only customizing the information in the track directives. The rest of the JavaScript is left as it was generated by Friendbuy.

When you have your widget code customized, you’ll need to place it in the head of your document, like so:

<head>
    <!-- css, javascript, meta tags, etc. -->
    [Place Friendbuy JS here]
</head>
<body>...

3. Place the Button

The last thing you need to do for the Product Share widget is place the share button on your page. You can put the button anywhere you would like. For our example we’ll place it on our page directly beneath the heading for the page:

<body>
    <h1>Our Amazing Oatmeal Cookies</h1>
    <div class="friendbuy-my_widget_identifier"></div>
    ...
</body>

Note that there is nothing within the div, it is just used as a placeholder and the actual button will be placed by the JavaScript when it executes in the browser.

Wrap Up

Now you see how easy it is to get a Product Share widget set up with Friendbuy. Start by designing the widget in the application, then grab the code and customize it for your product. Finally, place the share button where you want it to appear on the product page. Remember that you are able to edit copy and design of the widget from within Friendbuy at any time without needing to edit the code on your page.

Once you have the Product Share code on your site it is a good idea to run a test by visting your product page and sharing it. Make sure the referral URL brings you to the page of the product that was shared.


Refer a Friend

Friendbuy makes it easy to have a dedicated referral page on your website. The Refer a Friend widget is designed to be embedded directly into a page: the button is not required. Additionally, there’s no requirement for a purchase or a product to populate the content of the widget. We recommend you put the Refer a Friend widget on a page on your site and give it a nice URL like yoursite.com/refer. With the Refer a Friend widget on your site you will add one of the pillars of an solid referral strategy.

1. Get the Widget Code

The first thing you’ll need to do is generate the code for the Refer a Friend widget. Log in to your Friendbuy account and create a new widget, then choose Standard Widgets on the first screen. Go through the prompts to choose a theme and customize the message. After that you’ll see an option to get the code.

2. Customize Code

Once you have the widget code, you’ll need to customize it for your environment. In this Quickstart we’re going to assume that the system is running on PHP. Note: we are assuming a variable called $user that identifies the current user. This is optional but we recommend you pass an identifier for the current user whenever you can. Without an ID, Friendbuy can not identify the sharer responsible for a conversion.

<script type="text/javascript">
    window['friendbuy'] = window['friendbuy'] || [];
    window['friendbuy'].push(['site', 'site-fffffff-host']);
    window['friendbuy'].push(['track', 'customer',
        {
            id: '<?php echo user->getId() ?>'
        }
    ]);

    window['friendbuy'].push([
        'widget', 'my_widget_identifier'
    ]);

    (function (f, r, n, d, b, y) {
        b = f.createElement(r), y = f.getElementsByTagName(r)[0];b.async = 1;b.src = n;y.parentNode.insertBefore(b, y);
    })(document, 'script', '//djnf6e5yyirys.cloudfront.net/js/friendbuy.min.js');
</script>

Note that we are only customizing the information in the track directives. The rest of the JavaScript is left as it was generated by Friendbuy.

When you have your widget code customized, you’ll need to place it in the head of your document, like so:

<head>
    <!-- css, javascript, meta tags, etc. -->
    [Place Friendbuy JS here]
</head>
<body>...

3. Embed the Widget

The widget will already be configured as an embed instead of a modal triggered by a button. So the the last thing you need to do is put the widget where you want it on the page. In our example we’ll place it on our page directly beneath the heading:

<body>
    <h1>Sharing is Caring</h1>
    <div class="friendbuy-my_widget_identifier"></div>
    ...
</body>

Note that there is nothing within the div, it is just used as a placeholder and the widget will be embedded by the JavaScript when it executes in the browser.

Wrap Up

A dedicated Refer a Friend page is a great idea for building a referral program. As you can see, Friendbuy makes it easy to design and place the widget anywhere on your site. Just create the widget, customize the code for your environment, and deploy it on a page of your website or store. Remember that you are able to edit copy and design of the widget from within Friendbuy at any time without needing to edit the code on your page.

Once you have the Refer a Friend widget on your site it is a good idea to run a test by going to the page, sharing, and visiting the share URL produced.