1. Home
  2. Knowledge Base
  3. Developer Articles
  4. Javascript API

Javascript API

The Fera javascript API allows you to customize the behavior of Fera in the frontend. Make sure that you’ve included thebananastand.js file on pages that you want to use the javascript API on.

Why we push methods to an array

In order to not be dependent on the timing of when the bananastand.js file is loaded, rather than running methods directly on the Fera JS file, we push the method name with it’s data parameters to a global array variable. The window as __bsio has the global variable assigned.

When the BananaStand.App class initializes it goes through the stack of methods pushed into the global window.__bsio and runs the methods. Afterwards, it replaces the __bsio.pushmethod by assigning __bsio to Banana Stand.App.

Javascript API Methods Available

To run one of these API methods simply push it to the __bsio stack like this:

__bsio = __bsio || []; // Run this in-case Banana Stand JS has not yet loaded.
__bsio.push({ action: 'pushEvent', data: { event_type: 'add_to_cart' }}); // Push your API method on the stack to get called ASAP.

Set Current Customer

Using this method lets you set the ID of the currently logged in or identified customer in your system.

This customer ID you are setting is the ID of the customer in your system. If your primary means of looking up a customer is by anything other than their email address, it’s not recommended to use their email address as their identifier (although it is allowed).

Example

__bsio = __bsio || [];
__bsio.push({ action: 'setCustomerId', customer_id: '123-im-a-customer-id'});

Note: If a customer ID is not set then the system will treat the current person like a visitor and assign the visitor a UUID that will follow them via their cookies.

Set Current Product

To tell Fera what current product is being watched or acted upon you can use the setProductId method.

Example of Settings Current Product

__bsio = __bsio || [];
__bsio.push({ action: 'setProductId', product_id: '123-im-a-product-id'});

The product_id value can be really anything you want but if you’re using a standard eCommerce system it should be
the ID of your product not the sku.

Start Viewing a Product Page

To be able to tell Fera that the current customer is looking at the current product, run this code:

__bsio = __bsio || [];
__bsio.push({ action: "startProductPageViewing" });

Pushing an Event

The Fera javascript API has pushing events as the most common use case. Pushing events is asynchronous and extremely fast -typically under 80ms.

Pushing an event takes the following parameters as the data object:

Parameter Required? Data Type Description
event_code yes string What type of event are you pushing? See here for a reference of all the different types of event codes you can pass.
customer_id optional string Do you know what the ID of the customer on your system is? If not specified Fera will just use the customer ID specified by the setCustomerIdmethod above. When there isn’t a specified customer then Fera will use a cookie-stored visitor ID that it generated upon first request.
product_id optional string Do you know what the ID of the product on your system is? When it’s not specified Fera will just use the product ID specified by the setProductId method above.
async optional boolean Should the event be processed by the server immediately? Requests can take longer, but you can use the callback after the event is pushed to do certain things. (default: false)

In the following 4 examples since we aren’t specifying a customer ID or a product ID it uses the info that was previously set by the setCustomerId and setProductId methods described above. This is the most common case.

Push Page View

__bsio = __bsio || [];
__bsio.push({ action: 'pushEvent', data: { event_type: 'page_view'} });

Second Example: Simple Order Event Push

__bsio = __bsio || [];
__bsio.push({ action: 'pushEvent', data: { event_type: 'order', } });
Second Example: Full Order Event Push
__bsio = __bsio || [];
__bsio.push({ action: 'pushEvent', data: { event_type: 'order', payload: 

{
  "order_id":      "12345", // Integer, String
  "number":        "order-5", // Integer, String
  "test":          false, // Boolean
  "canceled":      false, // Boolean

  "total":         10.0, // Float
  "total_usd":     10.0, // Float

  "created_at":    "2019-03-18T21:01:10+00:00", // (Optional) String (ISO 8601 format DateTime) 
  "modified_at":   "2019-03-18T21:01:10+00:00", // (Optional) String (ISO 8601 format DateTime)  

  "source_name":   "web", // (Optional) String

  "line_items":    [
   {
      "name":       "Subsription to Product 123", // String
      "quantity":   1, // Integer
      "total":      10.0, // Float
      "total_usd":  10.0, // Float
      "product": {
        "id":                   "product-123", // String
        "name":                 "Subscription 123", // String
        "status":               "complete", // (Optional) String
        "created_at":  "2019-03-18T21:01:10+00:00", // (Optional) String (ISO 8601 format DateTime) 
        "modified_at": "2019-03-18T21:01:10+00:00", // (Optional) String (ISO 8601 format DateTime) 
        "stock":                123, // (Optional) Integer, If null assumed to be infinite.
        "in_stock":             true, // (Optional) Boolean
        "url":                  "https://www.lootcrate.com/products/product-123", // String
        "thumbnail_url":        "https://cdn.lootcrate.com/products/product-123/image.png", // String
        "needs_shipping":       true, // (Optional) Boolean
        "hidden":               false, // (Optional) Boolean
        "variants":             {
          "id":                   "product-123-variation1", // String
          "name":                 "Subscription 123 - Variation 1",
          "stock":                10, // (Optional) Integer, String Only used if stock is not specified by parent product schema.
          "in_stock":             true, // (Optional) String, Boolean
          "thumbnail_url":        "https://cdn.lootcrate.com/products/product-123/variation1/image.png", // (Optional) String
        }, // (Optional)
        "platform_data":        { "any": "data" } // (Optional) Hash/Object of attributes to store about the product specific to the integration platform (can be used in future filters)
      }
    }
  ],
  "customer":      { // (Optional)
    "id":          "98765421", // (Optional)
    "first_name":  "John", // (Optional)
    "last_name":   "Doe", // (Optional)
    "email":       "john.doe@example.com", // (Optional)
    "created_at":  "2019-03-18T21:01:10+00:00", // (Optional) String (ISO 8601 format DateTime) 
    "modified_at": "2019-03-18T21:01:10+00:00", // (Optional) String (ISO 8601 format DateTime) 

    "address": { // (Optional)
      "country_code": "US", // (Optional) String
      "region":       "CA", // (Optional) String
      "city":         "San Diego", // (Optional) String
      "zip":          "78730" // (Optional) String
    }
  },
}

} });

Third Example: Simple Product Add to Cart Event Push

__bsio = __bsio || [];
__bsio.push({ action: 'pushEvent', data: { event_type: 'add_to_cart'} });

Final Example: More Specific Add To Cart Event Push

Let’s say you didn’t want Fera to use the customer ID it stored in the browser and you you have multiple products that are on the page, so you want to push an “Add to Cart” event for a particular product on click. Here’s how you would do it:

__bsio = __bsio || [];
__bsio.push({ action: 'pushEvent', data: {
  event_type: 'add_to_cart',
  product_id: '213-id-of-product-added-to-cart'
} });

Was this article helpful?

Related Articles