Once your Nibble account is created, you will be provided with:

  • Login access to the Nibble Admin Panel at https://app.nibble.website/ where you can set up Rules for how Nibble acts. See our documentation on Getting Started with Nibble to learn more.
  • Your Nibble API Key and API Secret. Make sure to secure your API Secret - treat it as if it were a password. You may have been issued separate API Keys and API Secrets for your staging site and your product site - please take care to use the correct keys for each site.

Once you have these details, you can now embed the Nibble chat widget.

Step 1. Embedding the Widget

The widget JavaScript code should be embedded in any product pages where it will appear. To embed, simply reference the nibble-button.min.js file, and create a <nibble-button> element:

<script src="https://cdn.nibble.website/widget/nibble-button.min.js"></script>
<nibble-button ...></nibble-button>

The <nibble-button> element can be placed anywhere on your page. It has a number of required and optional attributes. See the Nibble widget documentation for more details.

Step 2. Adding Event Listeners

The Nibble widget expects two event listeners to be attached: nibble-session-start to manage the creation of a new Nibble negotiation chat; and nibble-session-end to handle the end of a Nibble (in particular when the negotiation is successful).

// Obtain the button element by whatever means you prefer
const nibbleButton = document.getElementsByTagName('nibble-button')[0]

// Add the two event listeners (see below for implementation)
nibbleButton.addEventListener('nibble-session-start', myNibbleStartFunction)
nibbleButton.addEventListener('nibble-session-end', myNibbleEndFunction)

Step 3. Implement Nibble Start

Your Nibble Start listener is responsible for ensuring that a REST API call is made to the Nibble Cloud API from a secure server. The listener should pass any information necessary for that call to the server, except for secure or sensitive information, which the server should retrieve on its own. Once the API call is made, the Nibble Cloud API response should be passed back via your listener to a success callback. Pseudocode:

function myNibbleStartFunction (event) {
  // event.detail will be an array with two elements
  // The first is a success callback, to be invoked when the
  // Nibble is successfully created
  const successCallback = event.detail[0]
  // The second is an error callback, to be invoked if an
  // error occurred when creating the Nibble
  const errorCallback = event.detail[1]

  // The listener should then instruct your server to call the
  // Nibble Cloud API and create a Nibble, passing it the
  // Product ID
  fetch('my.server/my.api.endpoint', {with_appropriate_options})

  // On successful Nibble creation, the JSON response from
  // the Nibble Cloud API should be returned
  // to the successCallback
  .then(response => response.json())
  .then(responseJson => successCallback(responseJson))

  // On failed session creation, pass an error message string
  // to the errorCallback
  .error(errorString => errorCallback(errorString))
}

Note that the response from the Nibble Cloud API should be parsed as JSON into a plain JavaScript object before being passed to the successCallback. See the relevant API page for details on creating a Nibble. Once successCallback is called, the Nibble Widget will then handle the rest of the negotiation, until the Nibble ends.

Step 4: Implement Nibble End

Your Nibble End listener is responsible for handling completed negotiations. Failed negotiations can generally be ignored; however a successful negotiation should be verified, and then the product added to the user’s basket at the negotiated price. In order to securely verify the Nibble, the listener should pass the Nibble information to a secure server, and the server should then verify it via the Nibble Cloud API. Pseudocode:

function mySessionEndFunction (event) {
  // event.detail will be an array with three elemnts
  // The first is the Nibble ID
  const nibbleId = event.detail[0]
  // The second is the session status, one of 'open', 'successful',
  // or 'failed'
  const sessionStatus = event.detail[1]
  // The third is an optional callback, used to clean up the
  // negotiation UI and/or assist in adding to the basket
  const finalizeCallback = event.detail[2]
  // The fourth parameter is the Nibble payload for verification.
  // You can pass this to your backend for it to validate the details
  // of the agreement.
  const verificationPayload = event.details[3]

  // Statuses that are not 'successful' can be safely ignored,
  // in which case just instruct the Nibble window to close.
  if (sessionStatus !== 'successful') {
    finalizeCallback({close: true})
  }
  if (sessionStatus === 'successful') {

    // The listener should then instruct your server to verify
    // the session status, and add to basket if needed.
    fetch('my.server/my.api.endpoint', {with_appropriate_options})

    // You may now instruct the Nibble If your software requires that
    // the user clicks a link to finish adding to basket, instruct
    // the Nibble widget to show that link. The widget will not
    // close without user interaction
    .then(() => finalizeCallback({link: 'https://my.link/here'}))
  }
}

Step 5: Verify Nibble Data and Apply Discount

After a successful Nibble (i.e. a deal has been reached and a discount agreed), your server-side endpoint should next:

5.1. Verify the Nibble data is correct and has not been tampered with

Given the nibbleId and payload you received from the nibble-session-end listener, you can either call the Get Nibble API endpoint to securely obtain the Nibble details, or you can cryptographically verify that the payload is legitimate.

Either way you will have enough trusted information to know the agreed price and any addon items (free gifts)

5.2 Add the relevant item(s) to cart

For product negotiations, the item will need to be added to the user’s cart. The Get Nibble response and the payload contain the product ID, variant ID, quantity and discounted price. You must ensure that the agreed quantity is added to cart - the quantity can be changed during a negotiation, and the discounted price is based on the total price, taking quantity into account.

For both product and cart negotiations, a free gift may have also been agreed on. If so, an addon item will be present in the Get Nibble response and payload with the product Id of the item to be added to cart.

5.3 Apply the agreed discount

The Get Nibble response and the payload both contain a discounted price, which is the price that Nibble agreed to during negotiation. You should apply that discounted price in a manner appropriate to your system. For product negotiations, we recommend changing the item price if possible. If not, custom discount codes are a possibility.

You should take care to ensure that any discount you apply cannot be abused, reused or misapplied to other items or carts.

5.4. Take any next action as needed

Both the Get Session response and the payload contain information on the ’next action’. This is determined by the button the user may have clicked at the end of their chat: ‘Add to Basket and Continue Shopping’ or ‘Checkout Now’. If the next action is 'checkout', you should redirect the user’s browser directly to checkout; if it is just add_to_basket, add the item(s) to cart and allow the user to continue shopping. Remember to call the finalizeCallback to ensure that the Nibble chat widget is dismissed.

Step 6: Report Successful Transactions

After a successful negotiation, if the user added the product to their basket and successfully completed a transaction for that item, you need to inform Nibble of that sale, by invoking the Report Sale endpoint.