Customize/Extend Global‑e Cartridge functionality
Global-e Cartridges are built and written following all requirements and recommendations for SFCC LINK Partners. This means that by installing the Global-e cartridge you don't have to change anything in the app_storefront_base cartridge, but that also means that Global-e does not recommend you to change anything directly in the int_globale cartridge.
If you need to customize/extend any logic in the Global-e extension cartridge you have to follow the recommendations of SFCC in regards to customizing/extending the app_storefront_base cartridge and apply them to the int_globale_sfra (or int_globale_sitegenesis) cartridge in the same way.
So if, for example, you need to customize/extend any Controller/Model or template from the int_globale cartridge - you need to make a copy of that file or extend it in int_globale_sfra or int_globale_sitegenesis cartridge and put all of your customization/extensions there.
Pay attention: some templates in int_globale_sitegenesis were overridden from basic SiteGenesis (Pipelines/Controllers) cartridges and in a few places hardcoded the id of the core cartridge (like this one: importScript( 'app_storefront_core:catalog/libCompareList.ds' )) - please change the id of the cartridge to the core cartridge that is used in your project's code (if it is required).
Properties and Translations
Global-e Cartridge has its own globale.properties file (int_globale/cartridge/templates/resources/globale.properties). It contains only English translations, so if you want to show localized Global-e messages you have to translate them to all your desired locales and put them into an extension cartridge (int_globale_sitegenesis or int_globale_sfra).
Checkout Analytics Data Implementation
Once a customer started the Global‑e checkout flow, Global‑e Client JS SDK will notify the client (Customer`s browser parent window from Global‑e Checkout iframe) on every step loaded via triggering a JavaScript event, for some steps, the data of the Basket/Order is passed as the parameter to the function which will be handling the event. By default, the OnCheckoutStepLoaded event will be triggered twice, once for the initial checkout page load and the second time for the checkout confirmation page. Here is the example of how the Checkout Analytics Data can be integrated into your int_globale_{extension}/cartridge/client/default/js/geScriptLoader.js:
Checkout Analytics Data implementation
/**
* Handler function of 'GlobalE.OnCheckoutStepLoadedHandler' event
* @param {Object} data - Event data
*/
GeScriptLoader.prototype.onCheckoutStepLoadedHandler = function (data) {
try {
if (data.StepId === data.Steps.CONFIRMATION) {
// stop sending keepAlive ajax call
if (('globaleKeepAlive' in window) && window.globaleKeepAlive) {
clearInterval(window.globaleKeepAlive);
}
}
/**
* If you need to implement the frontend analytics please put it here
*/
/**
* Only for Backend Analytics, like standard SFCC Merchant Tools / Analytics / Purchase Reports.
* Should be handled in Globale-Analytics controller
*/
var geIframe = document.querySelector('#gle_iframe');
Helpers.makeJsonAjaxCall(geIframe.dataset.analyticsUrl, 'POST', JSON.stringify(data))
.then(function (response) { // eslint-disable-line no-unused-vars
// handle response
})
.catch(function (e) {
console.warn(e); // eslint-disable-line no-console
});
} catch (e) {
console.warn(e); // eslint-disable-line no-console
}
};
Global‑e Price API
Global-e cartridge int_globale contains several factories which you can use when you customize your files due to Global-e integration.
All available Global-e factories you will find at int_globale/cartridge/scripts/factories/globale/ folder. Here is the list of the most common price conversion Global-e factories:
Price
This factory will convert the price to the end-customer price using the end-customer currency set in the current session (session.custom.geCurrency). This factory will return the Global-e Money object (by default) but also can return the Global-e Price object if returnPriceObject is set to true. Path to the file (relatively to int_globale/cartridge/scripts/factories/globale/ folder): price.js Parameters:
Parameter | Type | Mandatory | By default | Description |
|---|---|---|---|---|
price | number | yes | Original price (in Merchant currency) of the product | |
productId | string | no | undefined | The product ID, if the resulting price is calculated for a specific SFCC product |
quantity | number | no | 1 | The quantity of the Product for which the Global-e price is being calculated |
skipRounding | boolean | no | false | If true - skip the currency rounding part of Global‑e price conversion |
formatOnly | boolean | no | false | If true - don't calculate Global‑e price, just format the value according to the end-customer currency |
returnPriceObject | boolean | no | false | If true - will return Global‑e Price object, otherwise - Global‑e Money object |
discount | boolean | no | false | If true - calculate the end-customer price as discounts (excluding rounding rules, etc.) |
Sample:
Global‑e Price factory
var globalePrice = require('*/cartridge/scripts/factories/globale/price');
var gePrice = globalePrice(11.12, 12345678);Money
This factory is extending the standard SFCC Money object, adding several extra properties to it. You can use it for example, when you need to work with a standard SFCC Money object. This factory will return the Global-e Money object.
Path to the file (relatively to int_globale/cartridge/scripts/factories/globale/ folder): money.js
Parameters:
Parameter | Type | Mandatory | By default | Description |
|---|---|---|---|---|
moneyValue | number | yes | Money value | |
currencyCode | string | yes | The currency code to which this Money will be formatted | |
originalMoney | object | no | null | The original Money object will be set as .super property of returned Global-e Money object. |
fixedPrice | boolean | no | false | If true - will set fixedPrice property of Global‑e Money to true, otherwise to false |
fixedPriceBookId | string | no | null | If true - will set fixedPriceBookId property of Global‑e Money to what is passed, otherwise to null |
Sample:
Global‑e Money factory
var globaleMoney = require('*/cartridge/scripts/factories/globale/money');
var geMoney = globaleMoney(11.12, 'USD');Option Model
This factory is extending the standard SFCC Product Option Model object, adding several extra properties to it. You have to use it when you calculate the price for product options (method optionModel.getPrice()). This factory will return the Global-e ProductOptionModel object.
Path to the file (relatively to int_globale/cartridge/scripts/factories/globale/ folder): optionModel.js
Parameters:
Parameter | Type | Mandatory | By default | Description |
|---|---|---|---|---|
optionModel | object | yes | Original Product Option Model will be set as .super to returned Global‑e Product Option Model object |
Sample:
Global‑e Product Option Model factory
var globaleOptionModel = require('*/cartridge/scripts/factories/globale/optionModel');
var geOptionModel = globaleOptionModel(product.optionModel);Price Model
This factory is extending the standard SFCC Product Price Model object, replacing the logic of existing methods (and values of properties) and adding several extra properties to it. You have to use it when you calculate the product price on PLP/PDP (and other similar) pages. This factory will return the Global-e Product Price Model object.
Path to the file (relatively to int_globale/cartridge/scripts/factories/globale/ folder): priceModel.js
Parameters:
Parameter | Type | Mandatory | By default | Description |
|---|---|---|---|---|
priceModel | object | yes | Original Product Price Model will be set as .super property to returned Global‑e Product Price Model object | |
product | object | yes | Original AFCC Product object will be set as .product property to returned Global‑e Product Price Model object |
Sample:
Global‑e Product Price Model factory
var globalePriceModel = require('*/cartridge/scripts/factories/globale/priceModel');
var gePriceModel = globalePriceModel(product.priceModel, product);Hiding non-applicable elements
If you have elements on your storefront that are only applicable to your domestic customers, we advise that you hide them from Global‑e customers by checking the Global‑e session. For example, the SFRA default cart template shows shipping methods. With Global‑e, these shipping methods do not apply to Global‑e customers since we use specific Global‑e shipping methods. As such, we only show these shipping methods if the customers are not Global‑e customers.
See an example of this logic in int_globale_sfra\cartridge\templates\default\cart\cartShippingMethodSelection.isml
cartShippingMethodSelection.isml
<isset name="globaleSession" value="${require('*/cartridge/models/globale/session')}" scope="page"/>
<isif condition="${!globaleSession.get('geOperatedCountry')}">
<div class="col-12">
...
</div>
</isif>Common elements to remove for Global‑e customers:
Domestic shipping methods on the cart page
PayPal payment method or other payment methods on the cart page
In-store pickup
Domestic customer service contact information
Display product status on Global‑e checkout
Global‑e allows the display of custom product status next to the product line item on Global‑e checkout and Global‑e confirmation email. You can set this product status to any value by adding an attribute containing the message to be displayed to the line item of the basket when sending it to Global‑e. Following SFCC guidelines, it is recommended that you create an extension of our base metadata model, located at int_globale\cartridge\models\globale\sendCart\product\decorators\metadata.js, to add this attribute. Below is a code example of sending back ordered product status to be displayed on Global‑e checkout. Please note that this is just an example and your logic to determine whether a product is back-ordered could be different.
Display back-ordered product status
/**
* Calculates and returns Global-e Product.MetaData API
* @returns {Object|null} - Global-e Product.MetaData API
*/
function getMetadata() {
var metadata = {};
var attributes = [];
// For backordered products
if (this.apiProduct.availabilityModel.availabilityStatus === dw.catalog.ProductAvailabilityModel.AVAILABILITY_STATUS_BACKORDER) {
var StringUtils = require('dw/util/StringUtils');
var Resource = require('dw/web/Resource');
var backOrderAttribute = {};
var backOrderedMsg = StringUtils.format(Resource.msg('global.allbackorder', 'locale', null));
if (this.apiProduct.availabilityModel.inventoryRecord != null &&
this.apiProduct.availabilityModel.inventoryRecord.inStockDate != null &&
this.apiProduct.availabilityModel.inventoryRecord.inStockDate > new Date()
) {
backOrderedMsg += StringUtils.format(
Resource.msg('global.inStockDate', 'locale', null),
this.apiProduct.availabilityModel.inventoryRecord.inStockDate.toDateString()
);
}
backOrderAttribute.AttributeKey = 'Backordered';
backOrderAttribute.AttributeValue = backOrderedMsg;
attributes.push(backOrderAttribute);
}
if (attributes.length > 0) {
metadata.Attributes = attributes;
}
return metadata;
}Global‑e Free Shipping Banner
Free shipping promotions for Global‑e operated countries are managed on the Global‑e platform and can be configured for each country individually. Allow us to display a free shipping promotion banner on your site by adding the container below either directly to your header template or via a content slot. Please note that if you choose to add it via the content slot, this content slot needs to be configured and active at all times.
Free Shipping Banner
<div id="GlobaleFreeShippingBannerContainer"> </div>