Developers

SmartPixel Overview

Friendbuy is deployed onto a merchants site via the Friendbuy SmartPixel. The SmartPixel is a simple javascript tag that is installed on the merchants site. The SmartPixel API allows developers to customize 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 SmartPixel 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 SmartPixel 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 my developer account


What’s New in SmartPixel

The Friendbuy SmartPixel v2 differs from v1 in the following ways:

Enhancement Description
Multiple widgets on a page You can now include as many Friendbuy widgets as you like on any given web page.
Specify widget by identifier Instead of having external rules that decide what widget appears on a page, in the SmartPixel API any widget can play any role, as long as its template supports it. You can thus unambiguously specify which widget should appear where.
Completely uniform interface Instead of having different _frnd and _frndq objects for different parts of APIv1,the SmartPixel API streamlines everything into a single friendbuy command list. You interact with the SmartPixel API in the same way throughout, and there are fewer variations to remember.

Overview

The Friendbuy SmartPixel API is accessed through the friendbuy JavaScript array. This array serves as a queue for your Friendbuy SmartPixel API actions. The approach is similar to the one used by Google Analytics.

To invoke the SmartPixel API, call the push(...) function with a three-element array. The array’s elements are declared in the following order:

  • A predefined string that specifies what to do
  • A predefined string that specifies what to do it on
  • A JavaScript object holding supplementary information for this command

The commands that can be pushed onto the friendbuy array fall into one of these categories:

Account Identification

Friendbuy provides services to a variety of socially-minded vendors. Thus, your web page will want to identify itself to Friendbuy as a page that belongs to you via Account Identification.

Data Tracking

Friendbuy can track information or actions that come from your customers. For example, your web page may specify one or more specific products bought by the customer. Use the Data Tracking API to convey this information.

Widget and Share Button Setup

You have full control over which of your widgets will appear where, and whether they pop up automatically or wait for a mouse click. The Widget Setup API determines the behavior of Friendbuy’s widget(s) on the current web page.

Configuration

Friendbuy’s services can be set up in different ways to suit your needs. For example, you can set up A/B testing for prospective customers. Use the Configuration API to set this up.

Event Handling

Your web page can be set up 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).

friendbuy Command Array

The friendbuy array is defined when the web page is first loaded. The API actions and information that are pushed onto this array determine the behavior of Friendbuy’s widget(s) on the current web page.

The friendbuy array is a plain JavaScript array that must be assigned to the top-level namespace (i.e., window). This code can be written out directly, or integrated into the website with dynamically generated data, as needed. Friendbuy’s JavaScript uses this array as the source of instructions for the delivery of a configured widget on your web page and tracking associated behavior:

window['friendbuy'] = window['friendbuy'] || [];
window['friendbuy'].push(['what_to_do', 'what_to_do_it_on',
    supplementary_information
]);
...

The Friendbuy SmartPixel API determines which widgets appear on your web page, but not what they look like. You alter the layout and appearance of a widget using Friendbuy’s editor.


Account Identification

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['site', 'site-d2a64238-www.test.com']);
...

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


Data Tracking

The track directive identifies something that you would like to follow when a customer navigates to your web page. Each trackable item is expected to have certain properties that are relevant to that item. Tracked information is also provided to the widget(s) on the page, in some cases determining what the widget displays or shares (if the user chooses to do so).

Order

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['track', 'order',
    {
        id: "0382138317",
        amount: "325.94",
        email: "email@example.org",
        new_customer: true
    }
]);
...

The order property indicates a purchase on your website. The supplementary information for an order property is an object with the following attributes:

Attribute Description
id 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 The dollar amount for the order.
email The email address provided by the person who made the purchase. Used by Friendbuy for fraud detection. This property is optional.
new_customer This attribute indicates that the order was made by a new customer (true) or an existing customer (false). This attribute takes in a Boolean value of true or false. This property is optional.

An order may be associated with a products array (see below) if the products purchased with the order are known. In this case, your JavaScript would have code such as:

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['track', 'order',
    {
        id: "0382138317",
        amount: "325.94",
        email: "email@example.org",
        new_customer: true
    }
]);
window['friendbuy'].push(['track', 'products',
    [
        {
            sku: "2579", 
            price: "22.00", 
            quantity: "1"
        },
        {
            sku: "4063",
            price: "76.00",
            quantity: "1" 
        }
    ]
]);
...

Tracking information such as order and products facilitates fine-grained targeting by your widget(s). 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.

Products

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['track', '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. The supplementary information for a products property is an array of objects, each of which can have the following attributes:

Attribute Description
sku An identifier for a purchased product
price The price of that product
quantity Indicates how many units of that product were purchased

A widget can use order and products to populate its content, in different combinations:

  • order by itself indicates a purchase for which product information is not available.
  • products by itself indicates a product focus without requiring a customer purchase.
  • Having both order and products can indicate a purchase where the purchased items are known.

Customer

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['track', 'customer',
    {
        id: "7896751",
        email: "email@example.org",
        first_name: "John",
        last_name: "Smith"
    }
]);
...
  • id 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.
  • email is the email address of the customer. Widgets will automatically populate the from field when sharing through email when email is present. This value is stored for use in fraud checking. The stored value will be updated if a new value is passed into the smartpixel.
  • first_name is the first name of the customer. This value will be stored and used in the future to facilitate personalization of widgets and communication. The stored value will be updated if a new value is passed into the smartpixel.
  • last_name is the last name of the customer. This will be stored and used in the future to facilitate personalization of widgets and communication. The stored value will be updated if a new value is passed into the smartpixel.

Widget and Share Button

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'widget_identifier']);
...

The widget directive sets up a Friendbuy widget on your web page. The only requirement of this directive is the 'widget_identifier' as specified using Friendbuy’s editor. This determines which widget to add to the page. The optional items take on default values if they are not explicitly supplied.

You may issue the widget directive multiple times: once for each Friendbuy widget that you would like to add to your web page.

Widget Identifier

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'dB-ecN']);
...

The widget identifier determines the widget to add to your web page. This is set using Friendbuy’s editor.

The example given above adds the widget whose identifier is 'dB-ecN' to the web page, attaching it to the element with the default selector (i.e., the element whose class is 'friendbuy-dB-ecN') using default widget options (i.e., no auto-popup, configured share button included).

Widget Selector

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'dB-ecN', '#offer-div']);
...

If you do not include a widget selector, the Friendbuy software looks for the element on your page whose class is 'friendbuy-widget_identifier', where widget_identifier is set using Friendbuy’s editor. If 'dB-ecN' is a popup widget, the configured share button will be added to the selected element, and clicking on that share button will make the widget appear.

The example below adds the widget whose identifier is 'aO-Ybn' to the web page with the default widget properties. Because the widget selector refers to elements whose class is 'refer-trigger', this example allows the same widget to be associated with more than one share button on the same page.

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'aO-Ybn', '.refer-trigger']);
...

Widget Options

As a final argument, an options object may be passed to the widget directive to specify custom settings, expressed as key-value pairs. The key determines the type of setting (e.g., configuration, parameters, etc.). Each configurable collection is then itself provided as a JavaScript object.

Configuration

Auto-Delay

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'Ca-kJo',
    {
        configuration: {
            auto_delay: 5000
        }
    }
]);
...

The auto_delay property within configuration 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.

The example above makes the 'Ca-kJo' widget appear automatically after 5 seconds. The widget can still be triggered manually if the user clicks on the configured share button that is placed in the web page element(s) whose class is 'friendbuy-Ca-kJo' (the default selector).

Inclusion of Share Button

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'jB-jMk',
    {
        configuration: {
            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 identifier must be attached to an element on the page such as a button or banner.

Additional Widget Selection/Customization Criteria

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'mC-hNm',
    {
        criteria: {
            limitedTime: true,
            customerType: 'VIP'
        }
    }
]);
...

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

Custom Content

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'an-InQ',
    {
        content: {
            firstname: "Maria",
            city: "Cybertown"
        }
    }
]);
...

You can personalize or customize the information in your widget using the content property. These values are visible to your widget’s template at the time that it is built. With the right template code, your widget can provide individualized or targeted information to a customer.

Additional Parameters

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', 'YA-qlp',
    {
        parameters: {
            survey: true,
            offercode: "BAZ-INGA"
        }
    }
]);
...

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


Event Handling

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', ...
...
window['friendbuy'].push(['subscribe', 'event_type',
    function (event_object) {
        // event handler code
    }
]);
...

To listen for client-side events, push the 'subscribe' directive onto the friendbuy array, with the following additional information (as illustrated above):

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

Make sure to push the 'subscribe' directive after all widgets have been specified for the web page.

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

widget.open

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', ...
...
window['friendbuy'].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:

Property Description
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 used when the widget was set up)
shareWidgetElement The HTML element that holds the widget

widget.close

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', ...
...
window['friendbuy'].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

window['friendbuy'] = window['friendbuy'] || [];
...
window['friendbuy'].push(['widget', ...
...
window['friendbuy'].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:

Property Description
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 website 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.


Visitor Status

The visitor_status service allows you to check whether a current user on your website has clicked on a Friendbuy link into that same site within the last hour. The service returns information about the share or personal URL that was clicked, and in particular will check if the share or personal URL also came from the current user (i.e., a self-referral).

Invoking Visitor Status

To invoke the Visitor Status service, push the 'invoke' directive onto the friendbuy array, as well as the string 'visitor_status', and a callback function to handle the information returned by the visitor_status as detailed below.

window['friendbuy'].push(['invoke', 'visitor_status',
    function(response) {
        //response handler code
    }
]);

Visitor Status Response

The callback function supplied to the visitor_status call accepts a single argument, which is a Javascript object with the following properties:

Property Description
friendbuy_click 'share', 'purl', or 'none'
share Information about the share, if friendbuy_click === 'share'
purl Information about the personal URL, if friendbuy_click === 'purl'
self_referred true or false, indicating whether the click was self-referred
id Identifier for the click
ip IP address of the user who clicked
ref Referring website
ua The user agent (browser) used for the click
timestamp When this response was formed
signature Friendbuy’s signature for this message

Start by looking at friendbuy_click. This is either 'share', 'purl', or 'none'. If friendbuy_click is 'none', then the current user has not clicked a friendbuy link into the merchant website in the past hour. If friendbuy_click is 'share', then a share property will hold information about the share. Finally, if friendbuy_click is 'purl', then a purl property includes information about the clicked personal URL. The self_referred property will either be true or false, indicating whether the current user is the same one that issued the share or personal URL that sent this user into the website. The timestamp and signature properties are supplied for security purposes, to ensure that outside parties cannot send a forged Friendbuy response to your website’s callback. Details on these properties are supplied below.

Security Concerns

To ensure that your callback function is indeed receiving an authentic visitor_status response from Friendbuy, Friendbuy signs the response in the following manner:

  1. Take the JSON response in the visitor_status request.
  2. Sort the response's attributes except for signature alphabetically, using Unix-style case-sensitive sorting order.
  3. Iterate through the sorted list of attributes, and concatenate the attribute names and values with no delimiters. If the value is itself an object, concatenate only its id.
  4. e.g.,
    {
        purl: { customer: "1234", id: "456" },
        friendbuy_click: "purl",
        self_referred: "true"
    }
    becomes:
        friendbuy_clickpurlpurl456self_referredtrue
    
  5. Sign the resulting string with HMAC-SHA1 using the merchant’s API Secret as the key.
  6. Base64 encode the resulting hash value.

Given this signature, merchant code can then:

  1. Generate the hash using the procedure above.
  2. Compare the hash to the value of the signature attribute in the visitor_status response. If the signatures match, the response is valid.
  3. Check the timestamp for something sufficiently recent to ensure that a malicious party is not merely triggering your callback with a copy of the original response (i.e., a replay attack).

The specific rule for determining a valid timestamp is up to you.