Salesforce Commerce Cloud

The document walks you through the step by step process of setting up the Firework SFCC Cartridge within your Salesforce Commerce Cloud backend.

Firework SFCC Cartridge Installation

The integration for this cartridge encompasses, the deployment of a generic cartridge combined with minor modification of templates inside the storefront code for the cartridge to be fully functional. No known dependency on any 3rd party product.

Download the Cartridge Package from Git Repository

GitHub - loopsocial/salesforce: Salesforce Firework IntegrationGitHub

Step 1 : Setup Cartridges Path

Now we’ll configure Cartridge Paths to ensure the Firework Cartridges are loaded.

In Administration > Sites > Manage Sites > YourSite > Settings we’ll add that Cartridges includes

int_firework_pd:

Next, in Administration > Sites > Manage Sites > Business Manager > Settings we’ll add that Cartridges includes

bm_firework_pd:bm_firework_dashboard:

Step 2 : Upload Metadata

After the installation of cartridge on your instance, we need to upload the metadata of the integration :

 Firework.zip

Before we import jobs please open the firework-job.xml inside the Firework.zip file and update context site-id to your desired site id

<context site-id="your_site_id"/>

To upload the file, navigate to Administration → Site Development → Site Import & Export → Upload →Choose Firework.zip to Upload

Import the metadata:

To Import the metadata, navigate to Administration → Site Development → Site Import & Export → Select the uploaded file → Click Import

Step 3 : Cartridge Installation Instructions

There are 3 cartridges in the zip folder

bm_firework_dashboard
bm_firework_pd
int_firework_pd

Please install these 3 cartridges on your SFCC cartridges directory

Enable Firework Cartridge

Navigate to Administration Organization Roles & Permissions Administrator Business Manager Modules

Then you can select the site or organization you want to enable the Firework Cartridge.

Step 4 : Setup Site Preference

Please Select Store and navigate to Merchant Tools → Site Preferences → Custom Site Preference Groups → fireworkDashboardConfig

Configuring Locale-Specific Product Information Import:

To ensure product information aligns with your site's intended audience, kindly input your site's locale ID in the configuration. By default, Firework will import product information based on the default locale.

Customizing Product Image Import for Specific View Types:

For precise image management, you can define specific view types for which images should be imported. Simply list the desired view types as comma-separated strings. If unspecified, Firework will import images for all view types by default.

Name	Value
Currency	Your Store Currency
Business Unique Id	Your Store Storefront URL
Contact Email	Your Store Contact Email
Image View Type	Image type should be Comma separated values for e.g "large","medium"
Locale Id	Your Locale site ID for e.g ja-JP

Name

Value

Currency

Your Store Currency

Business Unique Id

Your Store Storefront URL

Contact Email

Your Store Contact Email

Image View Type

Image type should be Comma separated values for e.g "large","medium"

Locale Id

Your Locale site ID for e.g ja-JP

Step 5 : Setup Your API Client on Salesforce Account Manager

Setup API client on demandware Account Manager with the following Configuration:

Login to Demandware Account Manager and Navigate to API Client → Add API Client → Setup Display Name, Password and Select Your Organization → Roles → Select your Production / Sandbox Instance for Commerce Cloud Developer Experience and Salesforce Commerce API

Default Scopes

mail
roles
tenantFilter
profile
tenant
Filter
openId

Allowed Scopes

sfcc.shopper-customers.register
sfcc.shopper-customers.login
sfcc.products.rw
sfcc.catalogs.rw

Redirect URIs

http://localhost:8080

https://admin.us02.dx.commercecloud.salesforce.com/oauth2-redirect.html

https://your_admin_URL/on/demandware.store/Sites-Site/default/oauth-callback

Important Step: Your_admin_RedirectURL you will get it from Firework API Configuration Window:

To get the Redirect URL please navigate to Select Site, Merchant Tools → Manage Firework → Firework Dashboard

Token Endpoint Auth Method: private_key_jwt

Access Token Format: JWT

Once you click Save, it will generate the API Client ID and you need to remember the password you set during client Registration, we will need it for the next step.

Step 6 : Firework API Configuration

To support the API Integration we need to enable the default site locale. Merchant Tools > Site Preferences > Locales and select default

Please navigate to Select Site Merchant Tools → Manage Firework → Firework Dashboard

ClientID and Password you already generated in STEP 5 will be used here.

How to find a Shortcode & Organization ID

Please navigate to Administration → Site Development → Salesforce Commerce API Settings

We need to get the Short code and Org ID to enable the SFCC API Communication.

Step 7 : Load Firework Dashboard

Navigate to Merchant Tools → Manage Firework → Firework Dashboard

It will ask you to Login to Your Firework Business Account.
Please enter your Firework email address and One time Passcode
After that you will be redirected to Select the Existing Business or create a new Business. After this selection you will land on the Salesforce Product Feed / Import tool page

Here is the video guide on how to login to a Firework account.

https://drive.google.com/file/d/1Hyoc6VSLT5LwhXGM7M4SYcrj_oP9RGBv/view?usp=sharing

You will land on the Salesforce Product Feed / Import tool page

When you click Import you will get a list of all products from your salesforce store.

From here you can import products directly from your salesforce store to Firework business store.

Navigate to Merchant Tools → Content → Page Designer

Select your Page which you want to add Widget to

You can select the layout from the Firework Components

Select the Channel and Playlist from the Widget Settings

Click Save and Close, you can see the Carousel Widget added to the Page.

The Firework widgets, being asynchronous, gracefully degrades and don’t block the loading of any page element.

Step 9 (optional): Steps to Add Integration script Manually to Common HTML header

Note: Perform these steps only if you are not using page designer and manually adding html embed to your web pages

Here are the instructions for manually adding the Firework Player widget to your SFCC (Salesforce Commerce Cloud) website:

Access your SFCC instance and navigate to the common header file:

Path: cartridges/app_storefront_base/cartridge/templates/default/common/htmlHead.isml

In the htmlHead.isml file, add the following code inside the tag:

<isscript>
var oauthCOObj = dw.object.CustomObjectMgr.getCustomObject('FireworkOauthCO',dw.system.Site.current.ID);
var getClientID =oauthCOObj.custom.fireworkClientId;
var getCartURL=dw.web.URLUtils.https('Cart-Show');
var getProductURL=dw.web.URLUtils.https('ProductDetail-Show');
var siteId=dw.system.Site.current.ID;
var shopVersion='v23_1';
</isscript>

After the section, add the following JavaScript code:

<script type="text/javascript">
if (window.localStorage) {
window.localStorage.setItem('fw_shop_version',"${shopVersion}");
window.localStorage.setItem('fw_site_id',"${siteId}");
window.localStorage.setItem('fw_cart_url',"${getCartURL}");
window.localStorage.setItem('fw_sfcc_id',"${getClientID}");
window.localStorage.setItem('fw_pd_url',"${getProductURL}");
}
</script>

Add the Firework Player widget scripts below the previous code:

<script async type="text/javascript" src="//asset.fwcdn3.com/js/fwn.js"></script>
<script async type="text/javascript" src="//asset.fwcdn3.com/js/analytics.js"></script>
<script async type="text/javascript" src="//asset.fwcdn3.com/js/integrations/salesforce.js"></script>

Save the changes to the htmlHead.isml file.
Push the updated code to your SFCC instance.
Test the website to ensure that product hydration and cart hydration are enabled with the Firework Player widget.

By following these steps, you will successfully add the Firework Player widget and integrate it with Salesforce Commerce Cloud on your website.

Step 10 : Enable Purchase Tracking

In order to enable purchase tracking for your Salesforce Commerce Cloud cartridge, please follow the instructions below:

Download the latest version of the cartridge code.
Locate the "confirmation.isml" file in your code base. You can find it at: /app_storefront_base/cartridge/templates/default/checkout/confirmation/confirmation.isml.
Open the "confirmation.isml" file and insert the following snippet at an appropriate location within the file:

<isif condition="${dw.system.Site.getCurrent().getCustomPreferenceValue('fireworkEnablePurchaseTrack')}">
    <isinclude template="util/modules_firework"/>
    <ispurchasetracking sadebug="0"/>
</isif>

Deploy Cartridge to your Salesforce Commerce Cloud Instance.
To activate purchase tracking, navigate to Merchant Tools > Site Preferences > Custom Site Preference Groups > Firework Dashboard Configuration.
Locate the "Activate Purchase Tracking" setting and set it to "Yes".
Save the configuration.

By following these steps, you will successfully insert the tracking script on the "confirmation.isml" file and activate purchase tracking for your Salesforce Commerce Cloud cartridge.

Step 11 : Enable Native / Instant Checkout

SFCC OPEN API Shop Data Set

Please set this data set into SFCC admin panel to access the OCAPI to enable the Instant / Native Cart Checkout

Navigate to

Administration > Site Development > Open Commerce API Settings

Just replace {{your_client_id}}

{
    "_v": "22.4",
    "clients": [
    {
        "client_id": "{{your_client_id}}",
        "resources": [
        {
            "resource_id": "/sessions",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/{basket_id}",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/{basket_id}/storefront",
            "methods": [
                "put"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/auth",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/reference",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*",
            "methods": [
                "get",
                "patch",
                "delete"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/billing_address",
            "methods": [
                "put"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/coupons",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/coupons/*",
            "methods": [
                "delete"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/customer",
            "methods": [
                "put"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/gift_certificate_items",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/gift_certificate_items/*",
            "methods": [
                "delete",
                "patch"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/items",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/items/*",
            "methods": [
                "delete",
                "patch"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/payment_instruments",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/payment_instruments/*",
            "methods": [
                "delete",
                "patch"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/payment_methods",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/shipments",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/shipments/*",
            "methods": [
                "delete",
                "patch"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/shipments/*/shipping_address",
            "methods": [
                "put"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/shipments/*/shipping_method",
            "methods": [
                "put"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/shipments/*/shipping_methods",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/orders",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/orders/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/orders/*/payment_instruments",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/orders/*/payment_instruments/*",
            "methods": [
                "delete",
                "patch"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/orders/*/payment_methods",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/auth",
            "methods": [
                "post",
                "delete"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/auth/trustedsystem",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*",
            "methods": [
                "get",
                "patch"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/addresses",
            "methods": [
                "get",
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/addresses/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/baskets",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/orders",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/password",
            "methods": [
                "put"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/payment_instruments",
            "methods": [
                "get",
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/payment_instruments/*",
            "methods": [
                "get",
                "delete"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/product_lists",
            "methods": [
                "get",
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/product_lists/*",
            "methods": [
                "get",
                "patch",
                "delete"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/product_lists/*/items",
            "methods": [
                "get",
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/product_lists/*/items/*",
            "methods": [
                "get",
                "patch",
                "delete"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/product_lists",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/product_lists/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/product_lists/*/items",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/product_lists/*/items/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/product_search",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/search_suggestion",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/products/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/categories/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/gift_certificate",
            "methods": [
                "post"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/promotions",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/promotions/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/stores",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/stores/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/content/*",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/content_search",
            "methods": [
                "get"
            ],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        }]
    }]
}