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
orplacements
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
*/
});
{
"phone": "+19999999999",
"email": "[email protected]"
}
INSTALLMENT:INITIALIZED
This event fires when the Bread placement has been initialized.
BreadPayments.on("INSTALLMENT:INITIALIZED", () =>
console.log("Bread placement initialized");
);
Updated 5 months ago