JavaScript API Documentation¶

Requirements¶

In order to use our API you must have our Social Analytics app installed.

Note

Remember to init API methods when widget is fully loaded (and object AddShoppersWidget exists). See the live example.

AddShoppersTracking¶

You can use the optional AddShoppersTracking object to configure global widget settings and override product details (especially if you are not using Product Schema). You can put this object anywhere on any page that has our Social Analytics app installed.

Global options:

id:
(string) ID of your shop, in standard installation this is already set by our Social Analytics app.

auto:
(bool) Auto popup the sharing window when the page is loaded.

header:
(string) Global header displayed in main sharing window.

campaign:
(string) Social Rewards campaign name (case sensitive, overrides URL filters).

lang:
(object) Object containing language settings.

widget: (string) Language used in widget sharing window.

like: (string) Language used in Like button.

Product details:

url: (string) Product url.

name: (string) Product name.

image: (string) Image url.

description: (string) Product description.

price: (string) Product price with currency symbol.

stock: (string) Stock status.

instock: (int) Number of units in stock (overrides stock).

productid: (string) Product id/SKU.

rating: (float) The rating for this product, must be within 1-5 range unless rating scale is specified below.

rating_min: (int) Minimal product rating (1 assumed if omitted).

rating_max: (int) Maximum product rating (5 assumed if omitted).

rating_count: (int) The count of product ratings.

review_count: (int) The count of product ratings.

Examples:

AddShoppersTracking = {
    lang: {
        widget: 'en_US'
    },
    name: 'Custom product',
    description: 'Custom description',
    price: '$9.99',
    rating: 4.7,
    rating_count: 11
}

Event¶

The subscribe/publish mechanism allows third party applications to be notified about AddShoppers Widget events.

bind¶

AddShoppersWidget.API.Event.bind(event, callback)

params

event: (string) Event name.

callback: (function) Callback function.

Binds a callback function to specific event. All params will be passed in a single key-value object.

events

load: fired when widget is fully loaded (args: event).

share: fired when user shares your product (args: event, source).

sign_in: fired when user signs in via social service or email login (args: event, source).

sign_out: fired when user signs out (args: event).

bigcommerce_created:

fired when BigCommerce user created (args: email, first_name, last_name, password).

bigcommerce_error:

fired when BigCommerce raise error (args: email, error).

Note

sign_in event will also be fired if the user is already signed in when the widget is loaded. The source param will be set to "existing_session", "widget" or "social_login" accordingly.

Examples:

AddShoppersWidget.API.Event.bind("share", function(params) { /* example params: {"source": "facebook", "event": "share"} */ });

AddShoppersWidget.API.Event.bind("sign_in", function(params) { /* example params: {"source": "existing_session", "event": "sign_in"} */ });

AddShoppersWidget.API.Event.bind("bigcommerce_created", function(params) { /* example params: {"email": "user@email.com", "password": "12chRandPass", ...} */ });

AddShoppersWidget.API.Event.bind("bigcommerce_error", function(params) { /* example params: {"email": "user@email.com", "error": "Account already exists"} */ });

See the live example on how to bind load or sign_in events before the widget is initialized for the first time.

User¶

The following methods provide information about the user.

session¶

AddShoppersWidget.API.User.session()

returns

services: Array of service names if the user is signed in, null otherwise.

Returns an array of service names that are signed in within the current user session or null if the user is not signed in.

Supported service names: twitter, facebook, email.

Examples:

> AddShoppersWidget.API.User.session();
null

> AddShoppersWidget.API.User.session();
["twitter"]

sign¶

AddShoppersWidget.API.User.sign(service)

params

service: (string) Service name.

Shows up AddShoppers Social Sign In window for the specified service.

Supported service names: twitter, facebook, linkedin, google, paypal.

Note

The window will not be shown if the user is already signed in.

Examples:

AddShoppersWidget.API.User.sign("twitter");

signed¶

AddShoppersWidget.API.User.signed(service)

params

service: (string) Service name.

returns

status: (bool) Returns the status of user session.

Returns true if the user is signed in with the specified service, false otherwise.

Supported service names: email, twitter, facebook, linkedin, google, paypal.

Note

You can also use any value that will return true if the user is signed in via any service.

Examples:

> AddShoppersWidget.API.User.signed("twitter");
true

> AddShoppersWidget.API.User.signed("any");
true

signed_data¶

AddShoppersWidget.API.User.signed_data()

returns

params: (object) User data from signed in services.

Returns user data from services in which user is signed in.

Supported keys:

twitter_name,

facebook_name, facebook_email,

linkedin_firstname, linkedin_lastname, linkedin_email,

google_firstname, google_lastname, google_email, google_picture,

paypal_firstname, paypal_lastname, paypal_email

Each returned object will also contain UTC timestamp and signature. Both params should be used to verify that the values originated from AddShoppers servers.

Verify signature

In order to verify the request you will need your API Secret key (can be found in Merchant Admin > Settings > API).

First, for each received parameter (not including signature), create a “key=value” string. Next, sort all the strings and concatenate them together. Finally, append the received string to the end of your API Secret key and calculate md5 hex digest of it, making sure it matches the signature param value. Depending on your setup, you may also want to verify the timestamp value.

Example:

# assume 'params' contains all the received params
p = []
signature = None

for key, value in params.items():
    if key == 'signature':
        signature = value
    else:
        p.append('%s=%s' % (key, value))

query = ADDSHOPPERS_SECRET_KEY + ''.join(sorted(p))
hashed = hashlib.md5(query).hexdigest()

if signature == hashed:
    # request verified

Usage

Put the button codes from “Social Login” app where you want the buttons to appear.
Bind the “sign_in” event. (See the live example.)

Example:

AddShoppersWidget.API.Event.bind("sign_in", callback_function);

Wait for the event to be fired. In callback_function use the signed_data() API call to get all data about the user.

Example:

var callback_function = function() {
    // User has signed in

    var data = AddShoppersWidget.API.User.signed_data();
    // data example: Object {facebook_name: "John Abram", facebook_email: "john@example.com"}
    // ...
};

At this point you have the data about the user and you can for example create an account within your eCommerce platform.

Make sure to always verify the signature and timestamp of received params (see above).

sign_out¶

AddShoppersWidget.API.User.sign_out()

returns

status: (bool) Returns true if user was successfully signed out.

Note

Logout from all social services at the same time.

Examples:

AddShoppersWidget.API.User.sign_out();

Social¶

The following methods allow interaction with social services and related features.

app¶

AddShoppersWidget.API.Social.app(service)

params

service: (string) Service name, defaults to twitter.

Shows up AddShoppers sharing box with the specified tab open.

Supported service names: twitter, facebook, email.

Examples:

AddShoppersWidget.API.Social.app("email");

AddShoppersWidget.API.Social.app(“email”);

Global¶

The following methods allow interaction with social services and related features.

lang¶

AddShoppersWidget.API.Global.lang(code)

params

code: (string) Language code, defaults to en_US.

Change the Widget’s language.

Note

You can change the initial language in Settings or using AddShoppersTracking object. This method should only be used if you have to support multiple languages dynamically.

Interested in translating AddShoppers into your language? Contact us.

Examples:

AddShoppersWidget.API.Global.lang('en_US')

JavaScript API Documentation¶

Requirements¶

AddShoppersTracking¶

Event¶

bind¶

User¶

session¶

sign¶

signed¶

signed_data¶

sign_out¶

Global¶

lang¶

Table Of Contents

Previous topic

url:	(string) Product url.
name:	(string) Product name.
image:	(string) Image url.
description:	(string) Product description.
price:	(string) Product price with currency symbol.
stock:	(string) Stock status.
instock:	(int) Number of units in stock (overrides stock).
productid:	(string) Product id/SKU.
rating:	(float) The rating for this product, must be within 1-5 range unless rating scale is specified below.
rating_min:	(int) Minimal product rating (1 assumed if omitted).
rating_max:	(int) Maximum product rating (5 assumed if omitted).
rating_count:	(int) The count of product ratings.
review_count:	(int) The count of product ratings.

event:	(string) Event name.
callback:	(function) Callback function.

bigcommerce_created:
load:	fired when widget is fully loaded (args: event).
share:	fired when user shares your product (args: event, source).
sign_in:	fired when user signs in via social service or email login (args: event, source).
sign_out:	fired when user signs out (args: event).
	fired when BigCommerce user created (args: email, first_name, last_name, password).
bigcommerce_error:
	fired when BigCommerce raise error (args: email, error).

Navigation

JavaScript API Documentation¶

Requirements¶

AddShoppersTracking¶

Event¶

bind¶

User¶

session¶

sign¶

signed¶

signed_data¶

sign_out¶

Social¶

app¶

Global¶

lang¶

Table Of Contents

Previous topic

Quick search

Navigation