Advanced Bread Features

Overview

The information laid out in Bread SDK Installation should cover a majority of the use cases for Bread. However there are certain Bread functionality features that can be used to enhance the experience. This is very technical documentation intended for developers.

Rendering Placements Programmatically

By default, Bread runs as soon as it is loaded on the page. In some cases, this can cause issues either with race conditions or modern web frameworks where the DOM ID that Bread renders onto gets re-rendered after initial page load.

You can render placements programmatically by taking the following steps in addition to the typical Bread placement flow:

setting Bread into manual mode
calling the init function when you want to render Bread

An example below:

BreadPayments.setup({
  integrationKey: "your-api-key-here", // setup Bread
  buyer: buyer // pass in buyer object if you want to allow checkouts
});


BreadPayments.setInitMode("manual"); // puts Bread into manual mode, is 'auto' by default

BreadPayments.registerPlacements(placements); // register placements on page

BreadPayments.init(); // call the 'init' function when you want Bread to render on the page

📘
The above example does not include defined buyer or placements variables. Please see https://platform-docs.breadpayments.com/bread-onboarding/docs/bread-sdk-installation for more information on what these variables should contain

Launching the Bread modal programmatically

By default, the Bread modal will launch when a customer clicks on the placement. However, the Bread modal can also be launched by calling the openExperienceForPlacement function. This function takes an array of placement objects and will launch them when called.

Example below:

BreadPayments.setup({
  integrationKey: "your-api-key-here", // setup Bread
  buyer: buyer // pass in buyer object if you want to allow checkouts
});

BreadPayments.registerPlacements(placements); // register Bread placements

BreadPayments.openExperienceForPlacement(placements); // open Bread modal for placements

📘
The above example does not include a defined placements variable. Please see https://platform-docs.breadpayments.com/bread-onboarding/docs/bread-sdk-installation for more information on what this variable should contain

Rendering an Embedded Bread Modal

The embedded functionality of the Bread SDK allows the bread experience to render inside a specified html element on the host page instead of as a modal.

To initialize the embedded experience you must first pass an additional field named containerID to the setup function on the BreadPayments object. The value to containerID should correspond to an HTML id on your page where the iframe should be embedded.

For example, if you want the Bread experience to load in a div element under the placement. Give the div an id, for example, <div id=”checkout-container”></div> and call your setup function, including that id in the options:

BreadPayments.setup({
  integrationKey: "your-api-key-here", // setup Bread
  containerID: "checkout-container", // id of div where you want Bread to render
  buyer: buyer // pass in buyer object if you want to allow checkouts
});

Once your setup function is configured you will have to attach the standard Bread required event listeners for the INSTALLMENT:APPLICATION_DECISIONED and INSTALLMENT:APPLICATION_CHECKOUT events.

Then you will need to tell Bread to render the modal in embedded mode using the setEmbedded function and passing a true value as a parameter. This function must be called before the registerPlacements function is called.

BreadPayments.setEmbedded(true); // set Bread in embedded mode by calling setEmbedded and passing a true value

BreadPayments.registerPlacements(placements); // registering placemetns

An full example of the JS configuration to render Bread in embedded mode would look like the following:

BreadPayments.setup({
  integrationKey: "your-api-key-here", // setup Bread
  containerID: "checkout-container", // id of div where you want Bread to render
  buyer: buyer // pass in buyer object if you want to allow checkouts
});

BreadPayments.on("INSTALLMENT:APPLICATION_DECISIONED", (installmentResult) => {
  // required function 
});

BreadPayments.on("INSTALLMENT:APPLICATION_CHECKOUT", (installmentResult) => {
   // required function 
});


BreadPayments.setEmbedded(true); // set Bread in embedded mode by calling setEmbedded and passing a true value

BreadPayments.registerPlacements(placements); // register placements

📘
This will render a Bread placement that will launch an embedded Bread experience when clicked. If you would like to render Bread in an embedded manner without requiring a click see the steps for launching Bread programmatically

Advanced Event Listeners

In order to render Bread, you are required to configure event listeners for the INSTALLMENT:APPLICATION_DECISIONED and INSTALLMENT:APPLICATION_CHECKOUT events. However, Bread has other event listeners that can be utilized if need be.

INSTALLMENT:CUSTOMER_OPEN

This event fires when the Bread modal is opened.

BreadPayments.on("INSTALLMENT:CUSTOMER_OPEN", (location, placement) => {
 /*
    location -  placement location that has been opened(from locationType in the object below)
    
    placement - placement data (domID, order, etc)
 */
});

{
    "allowCheckout": true,
    "domID": "bread-checkout-btn",
    "locationType": "checkout",
    "order": {
        "items": [
            {
                "name": "Smooth Product",
                "sku": "09-021302",
                "category": "",
                "unitPrice": {
                    "value": 11000,
                    "currency": "USD"
                },
                "unitTax": {
                    "value": 0,
                    "currency": "USD"
                },
                "brand": "Brand Name",
                "quantity": 1,
                "shippingDescription": "Ground",
                "shippingProvider": "UPS",
                "shippingCost": {
                    "value": 0,
                    "currency": "USD"
                }
            }
        ],
        "subTotal": {
            "value": 11000,
            "currency": "USD"
        },
        "totalDiscounts": {
            "value": 0,
            "currency": "USD"
        },
        "totalPrice": {
            "value": 14000,
            "currency": "USD"
        },
        "totalShipping": {
            "value": 0,
            "currency": "USD"
        },
        "totalTax": {
            "value": 3000,
            "currency": "USD"
        }
    }
}

INSTALLMENT:CUSTOMER_CLOSE

This event fires when the Bread modal is closed.

BreadPayments.on("INSTALLMENT:CUSTOMER_CLOSE", (data) => {
  /*
    data - customer data that has been collected at that point in the funnel
  */
});

{
    "givenName": "John",
    "familyName": "Smith",
    "phone": "2123344141",
    "email": "[email protected]",
    "address1": "323 something lane",
    "address2": "apt. B",
    "locality": "NYC",
    "region": "NY",
    "postalCode": "11222",
    "country": "US",
    "order": {
        "items": [
            {
                "name": "Smooth Product",
                "sku": "09-021302",
                "category": "",
                "unitPrice": {
                    "value": 11000,
                    "currency": "USD"
                },
                "unitTax": {
                    "value": 0,
                    "currency": "USD"
                },
                "brand": "Brand Name",
                "quantity": 1,
                "shippingDescription": "Ground",
                "shippingProvider": "UPS",
                "shippingCost": {
                    "value": 0,
                    "currency": "USD"
                }
            }
        ],
        "subTotal": {
            "value": 11000,
            "currency": "USD"
        },
        "totalDiscounts": {
            "value": 0,
            "currency": "USD"
        },
        "totalPrice": {
            "value": 14000,
            "currency": "USD"
        },
        "totalShipping": {
            "value": 0,
            "currency": "USD"
        },
        "totalTax": {
            "value": 3000,
            "currency": "USD"
        }
    }
}

INSTALLMENT:INITIALIZED

This event fires when the Bread placement has been initialized.

BreadPayments.on("INSTALLMENT:INITIALIZED", () =>
  console.log("Bread placement initialized");
);