Developers

Overview

API v1 is deprecated as of January 2014. Please see our latest documentation.

The Friendbuy client API provides a way for developers to integrate Friendbuy widgets for specific use cases. For example, create a post-purchase widget that tracks shares, referral clicks to your site, and referral purchases. You can use our API to:

  • Create a robust "refer a friend" program
  • Attach your customer ID to shares and referral purchases
  • Pass any other parameters to Friendbuy
Other applications of the Friendbuy API include:
  • Tracking specific customers who share and what they share
  • Enable product sharing by integrating your product catalog with Friendbuy widgets
  • Pass your custom tracking parameters into referral links to track sharing and referrals in your analytics solution
  • Trigger referral incentives for different conversions, such as purchases

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

Create developer account


API Overview

The Friendbuy API has two parts, a Data Object and function calls.

The Data Object is a JavaScript object that contains information about your account, the widget being displayed, and if desired, additional information about a particular web page. For example, the Data Object may specify one or more specific products purchased by the user. Use the Data Object to configure the data that is passed to Friendbuy’s JavaScript and to select the widget that is displayed on that page.

API function calls are used to respond to actions performed by a user on a Friendbuy widget. For example, a web page may respond to the completion of a successful share, or take note of when a Friendbuy widget has been opened or closed.


Data Object

The _frnd object is defined when the web page is first loaded. It contains data about the characteristics of the current web page, such as order, product, customer, and/or other page parameters. The properties of this object determine the behavior of Friendbuy’s widget on the current web page.

_frnd is a plain JavaScript object that must be assigned to the top-level namespace (i.e., window). This code can be written out directly, or integrated into the web site with dynamically generated data, as needed. Friendbuy’s JavaScript uses this object as an argument to perform its functions – primarily, the delivery of a configured widget on your web page and tracking associated behavior.

The following properties - order, page, and products - determine which widget-type appears on your web page, but not what it looks like. You alter the layout and appearance of a widget using Friendbuy’s editor.

The object’s properties may be assigned directly, as follows:

var _frnd = _frnd || {};
_frnd.property = property-value;

Site

var _frnd = _frnd || {};
_frnd.site = "site-d2a64238-www.test.com";

The site property identifies your merchant account whose widgets are to be included in the current web page. For accounts with multiple Friendbuy-capable web sites (i.e. multiple domains), the site property may also differentiate the specific site that is generating a Friendbuy widget.

Order

var _frnd = _frnd || {};
_frnd.order = {
    id: "0382138317",
    amount: "325.94" 
};    

The order property indicates that Friendbuy will deliver a "post-purchase widget" on the current web page, if a corresponding post-purchase widget has been configured in the Friendbuy platform.

The value of the order property is an object that may have these properties:

  • id is an identifier for the order. If order is present for a refer-a-friend widget and the order object does not have an id, it is set to a value that is auto-generated.
  • amount is the dollar amount for the order.

An order may be associated with a products array (see below) if the products purchased with the order are known. A Friendbuy Data Object such as this would have code such as:

var _frnd = _frnd || {};
_frnd.order = {
    id: "0382138317",
    amount: "325.94"
};
_frnd.products = [ 
    {
        sku: "2579", 
        price: "22.00", 
        quantity: "1"
    },
    {
        sku: "4063",
        price: "76.00",
        quantity: "1" 
    }
];

Supplying properties such as order and products facilitates fine-grained targeting by your widget. You can display specific content for certain products or launch a widget that is meant for customers who have already purchased something from your website.

Page

var _frnd = _frnd || {};
_frnd.page = "order_confirmation_page";

The presence of a page property indicates that Friendbuy will deliver a "standard widget" on the current web page, if a corresponding standard widget has been configured in the Friendbuy platform. The value of page – a string – must match exactly the "page name" for the corresponding widget (as configured in the Friendbuy platform).

Products

var _frnd = _frnd || {};
_frnd.products = [ 
    {
        sku: "2579", 
        price: "22.00", 
        quantity: "1"
    },
    {
        sku: "4063",
        price: "76.00", 
        quantity: "1"
    } 
];

The products property lists the products that are associated with a purchase. This is an array of objects, each of which can have the following properties:

  • sku is an identifier for a purchased product
  • price is the price of that product
  • quantity indicates how many units of that product were purchased.

The presence of a products property indicates that Friendbuy will deliver a “product detail widget” on the current web page, if a corresponding product detail widget has been configured in the Friendbuy platform. A product detail widget is one that retrieves product information from your product catalog feed to populate certain widget content.

Customer

var _frnd = _frnd || {};
_frnd.customer = { 
    id: "7896751"
};

customer is your identifier for associating a user with a share or a purchase. Certain widget templates can include a personal referral link, or personal URL, which is only generated when customer.id is present.

Widget and Share Button

Properties of the Data Object that apply directly to a widget or share button are described below:

Auto-Delay

var _frnd = _frnd || {};
_frnd.auto_delay = 5000;

The auto_delay property determines the auto-popup behavior of the widget. It is specified as the number of milliseconds to wait before the widget appears automatically. A value of 0 indicates manual widget invocation.

Inclusion of Share Button

var _frnd = _frnd || {};
_frnd.share_button = true;

share_button is a boolean that indicates whether the configured widget share button should be included or not. When share_button is false the Friendbuy widget ID must be attached to an element on the page such as a button or banner.

Additional Widget Selection/Customization Criteria

var _frnd = _frnd || {};
_frnd.criteria = { 
    limitedTime: true,
    customerType: 'VIP'
};

If your Friendbuy account level supports targeting, the criteria property can pass additional parameters for widget selection and customization. criteria is a collection of key-value pairs.

Additional Parameters

var _frnd = _frnd || {};
_frnd.parameters = { 
    survey: true,
    offercode: "BAZ-INGA" 
};

The parameters property is another collection of key-value pairs. These values are added to referral links to track sharing and referrals in your analytics solution.


Function Calls

Alongside _frnd, a companion object named _frndq (where q is for "queue") is used to perform client-side event handling. _frndq should be initialized as an empty array [], in the same script that defines _frnd:

var _frndq = _frndq || [];

To listen for events, call the push(...) function with a three-element array, with the array’s elements declared in the following order:

  • The string literal "subscribe"
  • A string indicating the event type to subscribe to (see below)
  • A function/callback that should handle this event

Events

The supported events and their accompanying event handlers are described below:

widget.open

var _frndq = _frndq || [];
_frndq.push([
    "subscribe", "widget.open", 
    function (widget) {
        // widget.open event handler code
    } 
]);

The "widget.open" event fires when a Friendbuy widget appears on the web page. When called, the subscribed event handler function is passed a Widget object as its lone argument, indicating the specific widget that opened.

Widget has a number of properties, including:

  • autoDelay: The number of milliseconds that elapsed before the widget automatically opened, or 0 if it was manually triggered. This property has the same value as the auto_delay property in the _frnd object.
  • shareWidgetDiv: The HTML element that holds the widget.

widget.close

var _frndq = _frndq || [];
_frndq.push([
    "subscribe", "widget.close", 
    function (widget) {
        // widget.close event handler code
    } 
]);

The "widget.close" event fires when a Friendbuy widget has been closed by the user. When called, the subscribed event handler function is passed a Widget object as its lone argument, indicating the specific widget that was closed.

This Widget object is the same one that is passed upon "widget.open".

share.success

var _frndq = _frndq || [];
_frndq.push([
    "subscribe", "share.success", 
    function (share) {
        // share.success event handler code
    } 
]);                        

The "share.success" event fires when the user successfully completes a share using the Friendbuy widget. When called, the subscribed event handler function is passed an object that describes the share that just took place. This object has the following properties:

  • id: A unique identifier for the share
  • network: The destination of the share (e.g., "facebook", "twitter", etc.)
  • message: The message that accompanied the share

Subscribing to the "share.success" event allows you to trigger any activity on your web site that can be based on shares by your customers. You can issue a thank-you popup, send the visitor to a different page intended solely for those who have shared something about your site, or customize your web page depending on the social network share destination or the shared message.